Sphinx - это библиотека Python для создания хорошей документации из набора текстовых файлов в формате RTST. Не инструмент, используемый для полнотекстового поиска
Я также хорошо знаю инструменты doxygen/phpdoc. Я пытаюсь выяснить, есть ли способ использовать Sphinx для документирования проектов php? или даже любые другие языки, отличные от python?
Sphinx и ReST могут использоваться как общие инструменты документации, по моему опыту. Там нет ничего о Sphinx, который обязывает вас использовать его только для проектов на основе Python. Например, в моей работе я использовал его для создания руководства пользователя и ссылки на XML-RPC API. В обоих случаях мне не приходилось использовать 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 для создания своей онлайн-документации по адресу www.doctrine-project.org. Они используют собственный пигмент для PHP. Документация доступна в Github по адресу https://github.com/doctrine/orm-documentation. Он включает в себя пользовательский файл PHP pygment css.
Кроме того, пакет python-pygments поставляется с множеством стилей флага, которые вы можете попробовать, изменив значение pygments_style = в вашем sphinx conf.py файл конфигурации. Например, чтобы попробовать pastie выделять 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 или при запуске проекта.
PS: вы можете увидеть очень хороший ответ на элементы с пользовательскими классами здесь.
Как вы видите, есть много инструментов, которые помогут вам в этом, иначе, если вам действительно нужно, проверьте это:
https://blog.simpleigh.com/2012/08/php-documentation-and-sphinx