Sphinx для документации по php-коду

По моему опыту, Sphinx и ReST могут использоваться как общие инструменты документации. В Sphinx нет ничего, что обязывало бы использовать его только для проектов на основе Python. Например, в моей работе я использовал его для создания руководства пользователя и ссылки на XML-RPC API. В обоих случаях мне не приходилось использовать sphinx.ext.autodoc или другие специальные sphinx.ext.autodoc Python. Документация была написана «вручную», в основном общие директивы REST, а не специальные директивы, предоставленные Sphinx. Для чего это стоит, мне еще не нужно было создавать настраиваемую директиву REST для документации, отличной от Python.

Даже если вы работаете с проектом PHP, я думаю, вы найдете Sphinx полезным. Например, большинство директив, предоставляемых специальной разметкой модуля , на самом деле довольно общие. Я не понимаю, почему вы не могли или не использовали эти конструкции для документирования материала на других языках, кроме Python. Аналогично, Sphinx довольно легко демонстрирует примеры кода на других языках . Существует даже значение конфигурации, чтобы изменить значение по умолчанию на любой язык, поддерживаемый Pygments (включая PHP). Если вы чувствуете особую амбициозность, вы даже можете создать расширение Sphinx, чтобы вырвать что-то, что связано с вашим PHP-кодом.

Все, что сказано, обязательно рассмотрите аудиторию для вашего проекта документации. Хотя я считаю, что Sphinx – отличный инструмент и будет рекомендовать его для широкого спектра проектов документации, если ваша аудитория ожидает чего-то еще, помните об этом. Например, если вы документируете проект Java, большая часть вашей аудитории может ожидать документы в стиле Javadoc. Если вы отклоняетесь от этого ожидания, убедитесь, что это не только для ударов (то есть, это дает вам лучшие документы, чем вы могли бы получить в противном случае), и будьте готовы (кратко) сделать так, чтобы вы делали по-другому (например, с помощью FAQ или введение).

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

Только что выпущено несколько дней назад: http://mark-story.com/posts/view/sphinx-phpdomain-released

CakePHP использует Sphinx для своей новой документации, и я написал phpdomain для sphinx. Хотя нет способа автоматически включать ваши блоки php doc в sphinx, я по-прежнему считаю его одним из лучших инструментов для создания документации. Это отлично подходит для более подробной описательной документации. Но с phpdomain вы также можете сделать api docs.

Проект Doctrine, ORM для PHP, использует Sphinx для создания своей онлайн-документации на сайте http://www.doctrine-project.org . Они используют собственный пигмент для PHP. Документация доступна в Github по адресу https://github.com/doctrine/orm-documentation . Он включает в себя пользовательский файл PHP pygment css.

Кроме того, пакет python-pygments поставляется со многими стилями пигментов, которые вы можете попробовать, изменив значение pygments_style = в конфигурационном файле sphinx conf.py. Например, чтобы опробовать пасте, выделив sytle, который является частью python-pygments, вы используете

 pygments_sytle = 'pastie' 

Насколько мне известно, вы можете документировать практически любой синтаксис в Sphinx, насколько вы не ограничиваете себя языками, поддерживаемыми autodoc. Вы можете создавать красивые ссылки API, используя стандартные директивы Sphinx, такие как .. class , .. method , .. function и другие. Они отлично работают независимо от исходного кода и не требуют автоматической генерации и связи с источниками.

Вы также можете создавать общие предупреждения с некоторым специальным классом, которые позже можно было бы связать с CSS:

 .. admonition Title :class: Ololo This text could be formatted any way you want, using the ``Ololo`` tag. 

Существуют также роли (они также позволяют настраивать классы) и другие средства добавления текста с некоторым специальным форматированием, если исходных указаний недостаточно для вас.

Если вы решили создать асинхронный docs из исходного кода, убедитесь, что вы отключили проверку покрытия кода и других связанных с кодом функций в conf.py или при conf.py проекта.

PS: Вы можете увидеть очень хороший ответ на элементы с пользовательскими классами здесь .

Как вы видите, есть много инструментов, которые помогут вам в этом, иначе, если вам действительно нужно, проверьте это:

https://blog.simpleigh.com/2012/08/php-documentation-and-sphinx