Как сохранить синхронизированную документацию для каждой версии?

Question

Я работаю над небольшим игрушечным проектом, который получает все больше и больше релизов. До сих пор документация была просто набором страниц в блоге WordPress, который я настроил для проекта. Однако с течением времени новые версии выходят, и я должен обновить онлайн-документацию, чтобы она соответствовала самой последней версии.

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

Тривиальная идея состоит в том, чтобы создать текущие документы со страниц WordPress, сохранить их в SVN и, следовательно, в пакете релиза, повторяя процедуру при каждом новом выпуске. К сожалению, HTML-код, который я получаю, должен быть взломан вручную для исправления ссылок (или мне следует взломать WordPress, чтобы использовать BASE, чтобы HTML-код легко перемещался, что я не хочу делать).

Как мне справиться с требованиями наличия одновременно:

1. просматриваемая пользователем документация для соответствующей версии, включенной в загружаемый пакет
2. самая последняя документация, доступная онлайн (и правильно оформленная в соответствии с моей веб-темой)
3. поддерживать синхронизацию между svn и фактическим онлайн-контентом (в WordPress или чем-то еще, что хорошо вписывается в мою настройку WordPress)
4. прост в использовании

Спасибо

Редактировать: началось вознаграждение, чтобы посмотреть, смогу ли я заманить больше ответов. Я думаю, что это довольно важный вопрос, и было бы неплохо иметь несколько подсказок и мнений для будущих читателей.

Answer 1

WGet может конвертировать все ссылки в документе для вас. Смотрите опцию конвертировать ссылки:

http://www.gnu.org/software/wget/manual/html_node/Advanced-Usage.html

Использование этого в сочетании с другими методами может привести к решению.

Answer 2

Я проверю ваши страницы в SVN, а затем обновлю ваш веб-сервер с локальной рабочей копии SVN, когда вы будете готовы к выпуску. Поместите все в SVN - WordPress, CSS, HTML и т. Д.

Answer 3

Я думаю, что здесь нужно решить две проблемы

1. как и где сохранять документацию в соответствии с кодом
2. где опубликовать документацию

Для 1 я думаю, что лучше:

• храните документацию в репозитории (SVN или git или все, что вы уже используете для кода) в виде набора файлов, а не в БД, так как легче вести историю изменений (возможно, оставаться в паритете). с кодом выпуска
• использовать подход, при котором документация генерируется из набора исходных файлов (вы бы сохранили источники в репозитории), из которых создаются html-файлы для пакета распространения или для публикации в Интернете. Они могут отличаться, так как в Интернете вам потребуется хранить некоторую информацию version (в URL), которая вам не нужна при упаковке одного выпуска.

Для выполнения "2" есть несколько инструментов, которые могут генерировать статический сайт. Одним из них является Jekyll , он в рубине и выглядит довольно полным и настраиваемым.

Предполагая, что вы используете такой инструмент, как jekyll, и сохраняете файлы и источник в SVN, вы можете настроить репо следующим образом:

repo/
   tags/
      rel1.0/
         source/
         documentation/
      rel2.0/
         source/
         documentation/
      rel3.0/
         source/
         documentation/
   trunk/
      source/
      documentation/

То есть:

• Вы держите текущую документацию рядом с источником в транке
• Когда вы делаете релиз, вы создаете тег для релиза
• вы конфигурируете свой генератор документации для генерации документации для каждого из каталога repo / tags // Documentation так, чтобы документация для каждого релиза помещалась в каталог documents_site /

Итак, чтобы опубликовать документацию (пункт 2 выше):

• вы копируете на сервер содержимое каталога documents_site, помещая его в тот же базовый каталог, в котором установлена ​​ваша WordPress, или ссылаясь на него так, чтобы к каждому выпуску документа можно было обращаться как: http://yoursite/project/docs/relXX/
• вы создаете ссылку на текущую документацию выпуска, так что она всегда может быть достигнута как http://yoursite/project/docs/current

Хитрость в том, чтобы публиковать документацию всегда с правильным идентификатором выпуска (в URL, в файловой системе) и использовать ссылку (или перенаправление), чтобы убедиться, что «текущая документация» на веб-сервере указывает на текущий выпуск.

Answer 4

Для моих собственных проектов, если бы это было необходимо, я бы создал подкаталог для документации, и все файлы ссылались бы из известной базы там относительно. Например,

index.html -- refers to images/example.jpg
README
-- subdirs....
    images/example.jpg
    section/index.html  -- links back to '../index.html', 
                        -- refers to ../images/example.jpg

Если документы включены в загрузку SVN / tarball, то они читаются как есть. Если они генерируются из некоторых оригинальных файлов, они будут предварительно созданы для загружаемой версии.

Архивные версии документации можно распаковать / сгенерировать и поместить в именованные каталоги (например, docs / v1.05 /)

Это простой PHP-скрипт, который можно написать, чтобы получить список подкаталогов каталога / docs / с локального диска и отобразить список с выделением, например, самых последних.

Answer 5

Я видел, как некоторые программы используют справку и руководство . Но я пользователь Mac, и у меня нет опыта, чтобы понять, хорошо ли это. Я сам ищу решение для Mac.