Github + Markdown = Viewdocs

Original author: Jeff Lindsay
  • Translation
Для ПО с открытым исходным кодом очень большое значение имеет документация. На своем опыте я убедился, что написание хорошей документации зачастую даже важнее написания тестов.

Когда я перерос README на Github, я рассматривал только 2 варианта для документации: Github Pages и Read the Docs. К сожалению, у меня возникли проблемы с обоими. Главным образом, Read the Docs заставляет меня использовать reStructured Text, а Github Pages подразумевает поддержку отдельной ветки и использование генератора статичных страниц.

На самом деле, я бы хотел иметь нечто похожее на Gist.io, только для моего репозитория. Не найдя ничего подходящего, я написал это сам.

Я называю это Viewdocs. Сервис на лету создает страницы из markdown в папке docs Вашего проекта. Установка не требуется, просто следуйте соглашениям. Возможно для Вас это уже работает, т.к. markdown в папке docs — не такая уж редкость.

Шаблон, используемый по-умолчанию, был позаимствован у Gist.io.

Узнать больше Вы можете на сайте Viewdocs, который работает на базе Viewdocs. Или вот небольшой скринкаст-введение:

Share post

Similar posts

AdBlock has stolen the banner, but banners are not teeth — they will be back

More
Ads

Comments 15

    0
    Очень полезное средство, спасибо за перевод.
      +1
      Без панельки навигации по документации это ненамного лучше просмотра README-файлов прямо в Github.
        0
        Если вы переросли гитхабовский readme, то можете попробовать использовать backdoc. Генерируется полностью самостоятельный one-page-doc с навигацией и inline cтилями из простого маркдауна.
        0
        А связка Github Pages + Angular JS + Markdown.js (или альтернативы последних двух) не работает разьве?
          0
          Автору в Github Pages не нравится использование отдельного бранча.
            0
            Хммм Ну не знаю… Я пока не начал активно использовать, но мне кажется это не критично. Бранч меняется в два-три клика с помощью гитхабовского клиента. Ну или можно перманентно зачекаутить нужный бранч в отдельную папку.
          +4
          А Github Wiki чем автору не маркдаун?
            +2
            Просто следуйте соглашениям — каким соглашениям? Где хостится документация? Как инициируется её регенерация?

            Больше таких переводов! Так больше людей выучат английский.
              +1
              1. В репозитории Вашего проекта создаете папку docs
              2. Кладете в нее index.md.
              3. Заходите на http://<github-username>.viewdocs.io/<repository-name>
              4. Видите содержимое Вашего index.md (генерация происходит на лету)
                0
                Пример:
                При заходе на progrium.viewdocs.io/viewdocs
                Вы увидите содержимое github.com/progrium/viewdocs/blob/master/docs/index.md
                  0
                  Больше таких переводов! Так больше людей выучат английский.

                  Вы считаете, что в оригинальной статье тема раскрыта более полно?

                  Эта статья подразумевает, что Вы как минимум сталкивались с этими сервисами:
                  gist.io
                  pages.github.com
                  readthedocs.org
                    0
                    Конечно тема не раскрыта! Именно поэтому и не имеет смысла «переводить» подобное в оригинальном виде.
                  0
                  В копилку аналогичных сервисов:

                  www.roughdraft.io/
                  gist.io/

                  Работают на базе gist.github.com/, то есть им даже репозиторий не нужен.
                    0
                    А вот и документация вышла по Markdown: plutov.by/post/markdown_docs.
                      0
                      Не успели: «This domain was disabled at the request of John Gruber». :D

                    Only users with full accounts can post comments. Log in, please.