Недавно у меня возникла необходимость написать надлежащую, подобную прозе документацию исходного кода для PHP-клиента Diffbot . Посмотрев на несколько генераторов документации и даже предложив тег @prose для импорта связанных документов MD / reST в описания методов и классов, я понял, что просто нет идеального решения, с которым мы все можем согласиться (пока). Поэтому, пока я не расширил Sage с помощью токена @prose и парсинга reST, я выбирал ReadTheDocs и Sphinx.
RTD широко используется в промышленности. Он содержит мощные документы, такие как Guzzle , PhpSpec и многие другие. Он поддерживает reST вместе с MD (или, точнее, MD вместе с reST), что является огромным плюсом, поскольку файлы RST больше подходят для высокотехнологичных документов. Он может быть запущен локально и генерировать дружественные к оффлайн файлы HTML, но также может компилироваться из источника документации, доступного в Интернете, и автоматически размещаться как поддомен readthedocs.org .
Тем не менее, настройка его для проекта PHP имеет некоторые ограничения, поэтому мы пройдемся по основному руководству в этом руководстве.
TL; DR
Если вы просто ищете список команд для быстрого запуска и запуска:
sudo pip install sphinx sphinx-autobuild sphinx_rtd_theme sphinxcontrib-phpdomain mkdir docs cd docs sphinx-quickstart wget https://gist.githubusercontent.com/Swader/b16b18d50b8224f83d74/raw/b3c1d6912aefc390da905c8b2bb3660f513af713/requirements.txt
После быстрой настройки, чтобы активировать тему и подсветку синтаксиса PHP, запустите:
sed -i '/extensions = \[\]/ c\extensions = \["sphinxcontrib.phpdomain"\]' source/conf.py echo ' import sphinx_rtd_theme html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Set up PHP syntax highlights from sphinx.highlighting import lexers from pygments.lexers.web import PhpLexer lexers["php"] = PhpLexer(startinline=True, linenos=1) lexers["php-annotations"] = PhpLexer(startinline=True, linenos=1) primary_domain = "php" ' >> source/conf.py
Чтобы построить HTML:
make html
или
sphinx-build -b html source build
Последняя команда поддерживает несколько опций, которые вы можете добавить в микс.
Установка Сфинкса
ReadTheDocs использует Sphinx за кулисами и является сквозной реализацией Python. Чтобы использовать его, нам нужно установить несколько предварительных условий. Мы будем использовать нашу верную Homestead Improved, чтобы создать совершенно новую среду для игры.
После настройки виртуальной машины вставьте в нее SSH с помощью vagrant ssh и выполните:
sudo pip install sphinx sphinx-autobuild
Если у вас нет команды pip , следуйте официальным инструкциям, чтобы установить ее, или просто выполните следующее, если в Ubuntu:
sudo apt-get install python-sphinx python-setuptools sudo easy_install pip
Эти инструменты теперь сделали команду sphinx-quickstart доступной.
Рекомендуемый макет папки
Как правило, вы будете иметь:
- документация в той же папке, что и проект, который вы документируете, или…
- документация в собственном хранилище.
Если документация не охватывает несколько проектов или контекстов, рекомендуется, чтобы она находилась в той же папке, что и проект. Если вас волнует размер вашего проекта, когда Composer загружает его для использования, документы можно легко не .gitattributes в дистрибутив, поместив в файл .gitattributes (см. Здесь ).
Когда мы запускаем команду sphinx-quickstart , она запрашивает корневую папку наших документов. Это папка, в которую войдут все остальные подпапки, касающиеся документов. Обратите внимание, что это не корневая папка проекта. Если ваш проект в my-php-project , корень документации, скорее всего, будет в чем-то вроде my-php-project/docs .
Далее, Sphinx предлагает либо создать отдельную папку _build для скомпилированной версии документов (например, HTML), в то время как источники будут находиться в корневом каталоге (как определено на предыдущем шаге), либо создать две папки в корневом каталоге: source и build сохраняя рут в чистоте. Не стесняйтесь выбирать любой вариант, который вы предпочитаете (мы пошли с последним, для чистоты и структуры).
Следуйте остальным инструкциям, чтобы установить некоторые метаданные, выберите .rst в качестве расширения файла и, наконец, ответьте «нет» на все вопросы о дополнительных плагинах — они относятся к проектам Python и находятся за пределами нашей юрисдикции. Аналогично, когда вас попросят создать файлы make , примите.
Пользовательская тема
Сборка документов с помощью команды make html создает документы HTML в папке build . При открытии документов в браузере открывается экран, похожий на следующий:
Это не очень привлекательно. Эта тема намного стильнее и современнее. Давайте установим это.
pip install sphinx_rtd_theme
Затем в source папке корня документа найдите файл conf.py и добавьте следующую строку в начало, среди других операторов import :
import sphinx_rtd_theme
В том же файле измените название темы HTML:
html_theme = "sphinx_rtd_theme"
Наконец, сообщите Sphinx, где находится тема, спросив импортированный модуль:
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
Создание документов с помощью make html теперь должно привести к созданию значительно более красивого HTML:
Большинство тем следуют той же процедуре установки. Вот краткий список. Надеюсь, это будет расширяться в будущем.
Содержание
Во время quickstart у пользователя запрашивается имя главного файла (обычно это index ). Главный файл обычно содержит мало содержимого или вообще не содержит его; скорее он содержит только директивы.
Директива reST похожа на функцию — мощную конструкцию синтаксиса reST, которая принимает аргументы, опции и тело. Директива toctree является одной из них. Требуется опция maxdepth , указывающая максимальное количество уровней в одном пункте меню (например, глубина 2 — это Mainmenu -> Submenu1 но не -> Submenu2 ).
После опции идет пустая строка, а затем список включаемых файлов по одной на строку без расширений. Папки поддерживаются ( subfolder/filetoinclude ).
.. Test documentation master file, created by sphinx-quickstart on Sat Aug 8 20:15:44 2015. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to Test's documentation! ================================ Contents: .. toctree:: :maxdepth: 2 overview quickstart
В приведенном выше примере Sphinx распечатывает Contents: а затем расширенную версию оглавления, то есть маркированный список всех заголовков, найденных во включенных документах. Кроме того, многие авторы размещают дополнительную информацию в верхней части мастер-файла, чтобы тут же увидеть обзор библиотеки с высоты птичьего полета. Смотри жадину .
Определение toctree в мастер-файле будет автоматически отражено в левой навигационной панели ToC.
Давайте возьмем overview и быстрый запуск файлов из Guzzle, чтобы нам не приходилось писать свои собственные. Поместите их в корневой каталог документов и перестройте с помощью make html .
Теперь должна появиться документация, и левый ToC должен быть расширяемым с небольшими значками плюса:
Дополнительную информацию о директиве toctree и обо всем, что она может сделать, чтобы получить действительно настроенный вывод, смотрите здесь .
Синтаксис PHP
Если мы посмотрим на документ quickstart , мы заметим, что образцы PHP не выделены синтаксисом. Не удивительно, учитывая Sphinx по умолчанию на Python. Давайте это исправим.
В файле source/conf.py добавьте следующее:
from sphinx.highlighting import lexers from pygments.lexers.web import PhpLexer lexers['php'] = PhpLexer(startinline=True, linenos=1) lexers['php-annotations'] = PhpLexer(startinline=True, linenos=1) primary_domain = 'php'
Это импортирует лексер PHP и определяет определенные языковые подсказки блока кода как специально разбираемые модулем. Он также устанавливает режим документации по умолчанию на PHP, так что если вы опустите объявление языка в блоке кода, Sphinx просто предположит, что это PHP. Например, вместо:
.. code-block:: php use myNamespace/MyClass; ...
можно набрать:
.. code-block:: use myNamespace/MyClass; ...
После добавления вышеперечисленного в файл конфигурации требуется перестройка.
make html
Это должно создать синтаксис выделенных разделов PHP:
Домен PHP
Кроме того, мы можем установить домен PHP .
Домены представляют собой наборы ролевых ролей и директив, специфичных для языка программирования, что делает Sphinx гораздо более умелым в распознавании общих концепций и правильном их выделении и взаимосвязи. Домен PHP, изначально разработанный Mark Story , может быть установлен через:
sudo pip install sphinxcontrib-phpdomain
Расширение необходимо активировать, изменив строку extensions на:
extensions = ["sphinxcontrib.phpdomain"]
Давайте попробуем создать еще один файл reST с описанным классом PHP, чтобы мы могли видеть, насколько хорошо домен PHP делает свое дело. Мы создадим source/class.rst и добавим class в файл index.rst под всеми остальными. Затем мы поместим в class.rst следующее:
DateTime Class ============== .. php:class:: DateTime Datetime class .. php:method:: setDate($year, $month, $day) Set the date. :param int $year: The year. :param int $month: The month. :param int $day: The day. :returns: Either false on failure, or the datetime object for method chaining. .. php:method:: setTime($hour, $minute[, $second]) Set the time. :param int $hour: The hour :param int $minute: The minute :param int $second: The second :returns: Either false on failure, or the datetime object for method chaining. .. php:const:: ATOM Ymd\TH:i:sP
Если мы перестроим, мы получим что-то вроде этого:
Обратите внимание, что без установленного домена PHP этот экран будет пустым.
Это выглядит не так уж плохо, но могло бы быть и лучше. Мы оставим стиль на другой день.
Просмотреть источник
Обычно в документах в верхней части указывается ссылка на их исходные файлы, чтобы пользователи могли предлагать изменения, поднимать проблемы и отправлять запросы на получение улучшений, если они обнаруживают, что что-то не так.
В опциях конфигурации есть флаг, чтобы показать / скрыть эти ссылки на источники. По умолчанию они ведут к _sources/file где file — это _sources просматриваемый файл, а _sources — это каталог внутри каталога build т. build/_sources Все исходные файлы копируются в build/_sources во время процедуры сборки.
Мы этого не хотим. Мы будем размещать документы на Github, и мы хотим, чтобы источники указывали там, где бы они ни находились. Мы можем сделать это, добавив переменные контекста HTML в файл conf.py :
html_context = { "display_github": True, "github_user": "user", "github_repo": project, "github_version": "master", "conf_py_path": "/doc/", "source_suffix": source_suffix, }
Будьте осторожны, чтобы добавить этот блок после определения project , иначе вы получите ошибку о том, что переменная project не определена. conf.py это в conf.py как правило, безопасная ставка.
РЕСТ против МД
Для быстрого и грязного введения в reST, посмотрите это , но также посмотрите на пользовательскую разметку, добавленную командой Sphinx — эти дополнительные функции помогут вам извлечь максимальную пользу из вашей документации.
В ReST гораздо больше возможностей, чем в MD, поэтому для паритета и более простого перехода приведем отличное руководство по преобразованию и сравнение функций один к одному, аккуратно изложенные в табличном формате.
Добавление MD
Иногда вы можете не захотеть или не можете конвертировать существующую документацию MD в reST. Все в порядке, Sphinx может поддерживать MD / reST с двумя руками.
Для начала нам нужно установить модуль обработки MD:
sudo pip install recommonmark
Нам также нужно импортировать парсер в source/conf.py :
from recommonmark.parser import CommonMarkParser
Наконец, нам нужно указать Sphinx отправлять файлы .md в анализатор, заменив ранее определенную строку source_suffix :
source_suffix = ['.rst', '.md'] source_parsers = { '.md': CommonMarkParser, }
Если мы попробуем это, добавив в source файл файл testmd.md с содержимым:
# TestMD! We are testing md! ## Second heading! Testing MD files. --- echo "Here is some PHP code!"
Перестройка теперь должна показывать содержимое MD полностью обработанным — с одним предупреждением. Синтаксис не будет выделен (даже если мы поместим код в забор кода PHP). Если у кого-то есть представление о том, почему это происходит и как этого избежать, сообщите нам об этом в комментариях.
Хостинг на ReadTheDocs
Теперь, когда наша документация готова, мы можем разместить ее в Интернете. Для этой демонстрации мы создаем репозиторий с образцом контента по адресу http://github.com/sitepoint-editors/samplesphinx-php .
Чтобы разместить документы в Интернете, мы сначала добавим новый проект…
На следующем экране запрашивается соединение с Github. После импорта репозиториев, мы нажимаем «Создать» в том, из которого мы хотим создать проект RTD, и подтверждаем некоторые дополнительные значения, которые можно оставить по умолчанию.
После успешного завершения сборки наши документы должны быть активны:
Примечание: эта проверка раньше требовалась, но RTD, похоже, устранил проблему, и теперь вы можете использовать одно и то же объявление темы как в локальной версии, так и в реальной.
Расширения на RTD
Ранее в этом руководстве мы установили домен PHP для более простых описаний классов PHP на основе директив. Однако это расширение недоступно в ReadTheDocs.
К счастью, ReadTheDocs использует virtualenv и может установить практически любой модуль, который вы пожелаете. Для установки пользовательских модулей нам необходимо следующее:
- где-то в репозитории файл require.txt
- путь к этому файлу в разделе «
Advanced Settings» нашего проекта на ReadTheDocs
Чтобы получить файл требований, мы можем просто сохранить вывод команды pip freeze в файл:
pip freeze > requirements.txt
Команда freeze создаст длинный список модулей, и некоторые из них могут быть недоступны для установки в ReadTheDocs (например, в определенных Ubuntu). Вам нужно будет следить за ошибками на этапах сборки и удалять их из файла, одну за другой, до тех пор, пока не будет достигнут рабочий файл requirements или пока RTD не улучшит свой отчет о сборке, чтобы точнее помечать ошибки.
Для всех намерений и целей файл, такой как этот, должен быть прекрасно:
Babel==2.0 CommonMark==0.5.4 Jinja2==2.8 MarkupSafe==0.23 PyYAML==3.11 Pygments==2.0.2 Sphinx==1.3.1 sphinxcontrib-phpdomain==0.1.4 alabaster==0.7.6 argh==0.26.1 argparse==1.2.1 docutils==0.12 html5lib==0.999 meld3==0.6.10 pathtools==0.1.2 pytz==2015.4 recommonmark==0.2.0 six==1.5.2 snowballstemmer==1.2.0 sphinx-autobuild==0.5.2 sphinx-rtd-theme==0.1.8 wheel==0.24.0
После повторного запуска онлайн-сборки (происходит автоматически) документированный класс PHP должен быть доступен, как это было, когда мы тестировали локально.
Исправление проблем
ValueError: unknon locale: UTF-8
Возможно, вы получите сообщение об ошибке ValueError: unknown locale: UTF-8 в OS X после запуска sphinx-quickstart или make html . Если это произойдет, откройте файл ~/.bashrc (создайте его, если он не существует), вставьте содержимое:
export LC_ALL=en_US.UTF-8 export LANG=en_US.UTF-8
… Сохраните и закройте его, а затем загрузите его с помощью source ~/.bashrc команды source ~/.bashrc . Ошибка больше не должна появляться.
Содержание не отображается / устарело
Иногда при добавлении новых файлов для включения в index.rst на левой боковой панели будет устаревшим. Например, если щелкнуть файл, созданный до добавления нового файла, отобразится ToC с отсутствующим заголовком последнего файла. Причина этого неизвестна, но ее легко устранить, выполнив полную перестройку:
rm -rf build/ make html
Первая команда полностью удаляет содержимое папки сборки, заставляя Sphinx перегенерировать все в make html .
Ошибка сборки
Если ваши сборки терпят неудачу и вы не можете определить причину, иногда может помочь явное определение местоположения conf.py разделе « Advanced settings в Admin .
Вывод
В этом руководстве мы узнали, как быстро настроить рабочий процесс документации Sphinx для проектов PHP в изолированной виртуальной машине, чтобы установки не мешали работе нашей операционной системы. Мы установили подсветку PHP, настроили оглавление, установили пользовательскую тему, прошли через некоторый базовый синтаксис ReST и разместили наши документы в ReadTheDocs. В следующем посте мы сосредоточимся на стилизации, версиях документации и локализации.
Используете ли вы другой документооборот? Если да, то что и почему? Любые другие советы Sphinx / RTD? Дайте нам знать!