Я ищу инструмент для создания справки/документации, который бы удовлетворял таким требованиям:
- он должен поддерживать комментарий xmldoc, созданный компилятором С# или (даже лучше), напрямую поддерживает sandcastle
- он должен поддерживать импорт документов MS Word.
- он должен поддерживать создание ссылок из концептуальной документации в справочную документацию, подготовленную из исходного кода.
- было бы неплохо, если бы оно поддерживало концептуальное создание документа в MS Word
Подробнее. Мой проект - это платформа/библиотека для .NET. Он имеет несколько решений VS с полностью более чем 50 проектами на С#. Прежде всего, я хочу сгенерировать помощь (chm и help2 и help3 в будущем) из исходного кода моих проектов. Я буду ссылаться на эту документацию как "справочный документ". Sandcastle (особенно с использованием SCFB) может сделать это очень красиво. Но (я думаю, это очень распространенная ситуация). У меня есть дополнительная документация для рамки/библиотеки. Эта документация находится в файлах MS Word (5-10 файлов). Я буду ссылаться на эту документацию как на "концептуальный документ". Я хочу создать прочную справочную систему с концептуальным документом и справочным документом (например, MSDN). И я хочу, чтобы в концептуальной части справки содержались ссылки (URL), которые ссылаются на справочную часть справки для каждого имени типа .NET из фреймворка/библиотеки. (Очевидно, что любая справочная система - это просто HTML).
Проблема заключается в том, как создавать эти ссылки. Файлы MS Word ничего не знают о С# xmldoc. Sandcastle не поддерживает файлы Word. Поэтому я должен взять инструмент создания справки (HAT). К моменту, когда я не могу найти подходящего инструмента для меня. И я был бы очень признателен за любую помощь!
Камнем преткновения для всего инструмента является автоматическое создание ссылок. Я бы хотел, чтобы ссылки создавались автоматически, и они не могли генерировать (что может иметь место на сервере сборки). Почему автоматически? Потому что это позволяет легко переименовывать типы. Для примера. У меня есть текст в концептуальном документе: "для доступа к контексту обработки запроса используйте статическое свойство Current of XOperationContext type". Здесь XOperationContext - это имя типа. Я бы хотел, чтобы это стало ссылкой (URL) для спецификации класса XOperationContext в системе справки результатов без каких-либо значительных усилий. Я хотел бы отметить его в Word (возможно, с установленным плагином HAT) или в редакторе HAT, как-то вроде "сделайте эту ссылку слова, если это возможно". Во время генерации каждое такое слово станет ссылкой, если есть имя типа с таким именем.
Я знаю об этих инструментах:
- Toolsfactory Doc-o-Matic (используя сейчас)
- Innovasys DocumentX и HelpStudio
- ComponentOne Doc-to-Help
Doc-o-Matic поддерживает ссылки на автовосстановление. Поистине автоматически. Он пытается создать ссылку для каждого слова в PascalCase - блестяще. Но он не поддерживает MS Word. Программное обеспечение Innovasys и ComponentOne не поддерживают создание ссылок автоматически. Программное обеспечение Innovasys не поддерживает MS Word (я не уверен на 100% об этом).
Я попытался спросить на форумах Innovasys и ComponentOne. Пока не повезло. Сценарий сочной поддержки Innovasys, такой как мой: создание концептуального документа в отдельном инструменте - HelpStudio и генерация справки из исходного кода с помощью другого инструмента - DocumentX. Но нет возможности автоматически создавать ссылки и импортировать файлы MS Word.
Итак, поделитесь своим опытом для этой общей задачи (я уверен, что это должно быть распространено).
p.s. пожалуйста, дайте мне знать, если мне не удалось правильно объяснить мои мысли с точки зрения грамматики английского языка, я попробую еще один.