Дублированное обслуживание — код и документация [закрыто]

Question

Возможно, это не самое лучшее название — я был бы признателен, если бы кто-нибудь придумал лучшее после прочтения моей проблемы.Кроме того, я хочу сразу сказать, что я в основном самоучка в Интернете, поэтому может быть много инструментов, о которых я не знаю.

Я поддерживаю программное обеспечение, реализующее концепцию потокового программирования (FBP) как на Java, так и на C#.Для каждого из них у меня есть код:

• мой веб-сайт
• Система выпуска файлов SourceForge (zip-файлы или файлы jar)
• ИсточникForge SVN

Кроме того, у меня есть ссылки на версии и (иногда частичные) описания:

• мой веб-сайт (HTML)
• моя вики
• Javadoc

Также на моем веб-сайте и в SourceForge есть инструмент для рисования, который должен знать о последней версии Java-версии кода FBP.

Все довольно тщательно переплетено, но иногда я пропускаю ссылку!Несколько дней назад я понял, что уже давно не обновлял новости SourceForge для своего проекта, поэтому мне пришлось поторопиться и сделать это :-)

Я понимаю, что некоторые из этих машин, вероятно, избыточны, но в целом я не знаю, кто что смотрит.

Итак, мой вопрос в том, есть ли способ уменьшить все эти накладные расходы, например.Было бы неплохо использовать функцию «встраивания» HTML, чтобы я мог хотя бы хранить номер последней версии в одном месте.Я, вероятно, могу упростить перекрестные ссылки Java, но межъязыковое взаимодействие было бы еще лучше, но я думаю, это маловероятно.

Любые идеи будут приветствоваться.

Answer 1

Мне кажется, что вы хотите обновлять и поддерживать свою документацию как часть процесса сборки/развертывания, например.

1. строить
2. юнит-тест и т. д.
3. компилировать документацию
4. развертывать сборки
5. развернуть скомпилированную документацию

иначе ты всегда буду гоняться за твоим хвостом.Очевидно, что развертывание документации потребует разных решений относительно того, куда оно идет (например,скопировано на ваш сайт, отправлено по FTP в другое место и т. д.)

Я не уверен, что от всего этого существует панацея.Я сохраняю номера версий в файлах свойств/файлах конфигурации и выполняю соответствующий поиск/замену.Документация по коду, где это возможно, содержится в самом коде, а затем предварительно обрабатывается в моей сборке (шаг 3 выше).

Вы видели/использовали доксиген ?Это удовлетворит ваши требования к многоязычности и хорошо подходит для создания/поддержки документации.

Answer 2

Похоже, вам нужно автоматизировать процесс сборки/публикации.Я читаю Эта статья об О'Рейли некоторое время назад - кажется, у вас обоих довольно похожие ситуации?В его решении интенсивно используется Python, но, по крайней мере, оно может дать вам несколько идей.