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