На GitHub есть забавная штука под названием Страницы GitHub .
Его можно использовать двояко - можно либо сайт испортить, либо сделать доки для репозитория, об этом подробно написано в мануале.
Сайт нас сейчас не интересует, но доки к репозиторию — это та тема, которая нам нужна.
Например, я буду использовать проект на javascript, но это не имеет значения, Natural Docs поддерживает приличное количество языков, и это хорошо.
Значит, мы будем нужны себе NaturalDocs — поехали, скачаем, установим, посмотрим примеры.
Кроме того, нам необходимо создать стандартный новый проект , на GitHub. Вы сами разберетесь, что и как.
Например, назовем это Мой новый крутой проект (можно использовать уже существующий, но лучше тренироваться на новых котах).
Без промедления, сразу повеселимся страницы , как это: 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:// имя пользователя .
github.com/My-New-Cool-Project/, где вместо этого имя пользователя поставьте свой логин.
Теоретически мы должны получить пустую страницу с надписью «Моя страница GitHub» в левом верхнем углу.
Есть? Отлично, идем дальше.
Перейдем к коду и документации.
Сначала давай проверим, где мы находимся, и вернемся к мастер-бранчу.
git status
если начало выглядит так # On branch gh-pages
мы делаем git co master
Отлично, теперь в папке проекта в ветке master создадим следующую структуру: mkdir lib
mkdir doc
mkdir nd_internal
Первый — каталог для нашего кода, второй — место, где будет храниться документация, последний нужен для NaturalDocs.
Н.
Б.
оптимально отображать папку после создания nd_internal из-под git — в файл .
git/info/исключить добавьте новую строку 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 из каталога док — у вас должна получиться красивая страница с документацией.
Теперь коммитим все изменения, но пока ничего не пушим (если документы сгенерированы и на сайте ничего не изменилось, мы забыли закоммитить до следующий шаг).
После commit, нам нужно немного волшебства — подробное объяснение того, что происходит и почему, — пишет в своей заметке Доминик Митчелл.
Публикация подкаталога на страницах github , если вам интересно, переезжайте туда.
Я просто приведу пример своего сценария: #!/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.
Сейчас самое время сделать git push
В ответ мы должны получить что-то вроде: 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 [email protected]:Meettya/My-New-Cool-Project.git
f0005ad.a53b950 gh-pages -> gh-pages
48b901d.f0b787e master -> master
Важная вещь в этом — последние две строки: в обеих ветках должно быть два коммита.
И теперь мы идем по адресу http:// имя пользователя .
github.com/My-New-Cool-Project/ и проверьте, все ли на месте.
По идее, мы должны увидеть нашу замечательную документацию.
Теперь ничто не мешает вам сделать ссылку на нашу документацию в файле README и получать прибыль от автоматизированного документирования кода.
Мой тестовый проект, на который вы можете посмотреть, как и что было сделано - Расширенная библиотека jQuery .
Там можно найти примеры доков и всех скриптов, а также пример синтаксиса NaturalDocs. Теги: #JavaScript #естественная документация #github #Как #разработка веб-сайтов
-
Google Ускоряет Набор Сотрудников
19 Oct, 24 -
Преподавать Или Учиться?
19 Oct, 24 -
Беспроводное Электричество
19 Oct, 24 -
О Приложениях Uwp Для Разработчиков Wpf
19 Oct, 24 -
Wii Music Выйдет В Этом Году
19 Oct, 24
