У GitHub есть забавная штука, называется GitHub Pages.
Использоваться может двояко – можно или блог замутить, или сделать доки к репозитарию, в мануале об этом подробно написано.
Нас сейчас блог не интересует, а вот доки к репозитарию – тема что надо. Я для примера буду использовать javascript, но это не важно, Natural Docs поддерживает приличную пачку языков, чем и хорош.
Итак, нам понадобится сам NaturalDocs – идем, качаем, ставим, смотрим примеры.
Плюс к этому нам понадобится создать стандартный новый проект, на GitHub. Сами разберетесь, что да как. Для примера назовем его My New Cool Project (можно использовать и имеющийся, но тренироваться лучше на кошках новом).
Не откладывая в долгий ящик сразу забацаем pages, примерно так:
cd My-New-Cool-Project
git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index
git clean -fdx
echo "My GitHub Page" > index.html
git add .
git commit -a -m "First pages commit"
git push origin gh-pages
В процессе будут забавные надписи, что что-то там удаляется – это нормально :)
Попробуйте зайти на страничку http://username.github.com/My-New-Cool-Project/ , где вместо username ставим свой логин.
В теории мы должны получить чистую страничку с надписью “My GitHub Page” в верхнем левом углу. Есть? Отлично, двигаем дальше.
Займемся кодом и документацией.
Сперва проверим, где мы и вернемся в master brunch
если начало выглядит вот так
делаем
Отлично, теперь в папке проекта в master branch создадим вот такую структуру:
mkdir lib
mkdir doc
mkdir nd_internal
Первое – директория для нашего кода, второе – место, куда будет складываться документация, последнее нужно для NaturalDocs
NB. оптимально после создания вывести папку nd_internal из-под git – в файл .git/info/exclude добавьте новую строчку nd_internal/*
Теперь пишем какой-то код, сопровождая его комментами в стиле NaturalDocs (в папке lib).
Хорошо, положим код с комментами у нас есть, нам потребуется объяснить NaturalDocs, чего мы хотим. Требуется написать примерно следующее:
naturaldocs -i ./lib/ -o HTML ./doc/ -p ./nd_internal/
Где naturaldocs – название вашего исполняемого файла NaturalDocs, может отличаться от приведеного, разберетесь.
Если все пошло хорошо, увидите что-то типа:
Finding files and detecting changes...
Parsing 1 file...
Building 1 file...
Building 2 indexes...
Updating CSS file...
Done.
Попробуйте открыть файл index.html из каталога doc – должна получится красивая страничка с документацией.
Теперь мы коммитим все изменения, но пока ничего не пушим (если доки сгенерировали, а на сайте ничего не изменилось – забыли закоммитить перед следующим шагом).
После коммита нам потребуется немного магии – подробное объясние что и зачем происходит пишет Dominic Mitchell в своей заметке Publishing a subdirectory to github pages, если интересно – двигайте туда. Я же просто приведу пример своего скрипта:
#!/bin/bash
doc_dir='doc' # document directory
tmp_message='tmp_mess' # temporary files for changelog message
gh_pages='refs/heads/gh-pages' # refs to pages
parent_sha=$(git show-ref -s $gh_pages)
doc_sha=$(git ls-tree -d HEAD $doc_dir | awk '{print $3}')
git log --pretty=format:'%s' -n 1 $doc_dir > $tmp_message
new_commit=$(git commit-tree $doc_sha -p $parent_sha < $tmp_message )
rm $tmp_message
git update-ref $gh_pages $new_commit
echo "Docs update done"
По идее все должно было пройти хорошо и мы получили обновление документов в ветке gh-pages.
Теперь самое время сделать
В ответ у нас должно вывестись что-то типа:
Counting objects: 24, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (12/12), done.
Writing objects: 100% (13/13), 1.26 KiB, done.
Total 13 (delta 5), reused 0 (delta 0)
To git@github.com:Meettya/My-New-Cool-Project.git
f0005ad..a53b950 gh-pages -> gh-pages
48b901d..f0b787e master -> master
Важное в этом – последние две строки, должно быть два коммита в обе ветки.
И теперь мы идем на http://username.github.com/My-New-Cool-Project/ и проверяем, все ли на месте. В теории мы должны увидеть нашу замечательную документацию.
Теперь ничто не мешает сделат в README файле ссылку на наши доки и получить профит от автоматизированного документирования кода.
Мой тестовый проект, который можно покрутить на предмет как и что сделано – jQuery Enhance Library. Там вы сможете найти примеры доков и все скрипты а так же пример синтаксиса NaturalDocs.
