Сделай сам решение для интеграции блока аннотаций PHPDOC с Sphinx-doc (php.autodoc)
- У JS есть это: https://github.com/erikrose/sphinx-js
- Python имеет это: http://www.sphinx-doc.org/en/master/ext/autodoc.html
- У Java есть это: http://bronto.github.io/javasphinx/
- Свифт имеет это: https://github.com/AnarchyTools/anarchy_sphinx#swift-auto-documentation-extractor
PHP до сих пор не имеет экстрактора документации из исходного кода.
Не могли бы вы предложить, как автоматически извлекать аннотации PHPDOC из моего кода PHP в мою документацию, написанную в sphinx (контекстуально), и если такого решения не существует, как его сделать (например, с помощью https://github.com/nikic/PHP-Parser/tree/3.x)
Спасибо!
Решение
У меня на самом деле был тот же вопрос сегодня, и я нашел этот инструмент, который генерирует reStructuredText для каждого файла для пространства имен в каталоге: https://github.com/varspool/sphpdox/
Структура каталогов, если вы уже установили sphpdox используя композитор и запустить sphinx-quickstart (подробно в http://www.sphinx-doc.org/en/master/usage/quickstart.html) в папке с документацией (я использовал docs/ в этом примере:
src/
YourNameSpace/
YourClass.php
docs/
Makefile
source/
index.rst
conf.py
vendor/
bin/
sphpdox
Чтобы сгенерировать reST для вашего пространства имен, вы можете запустить:
./vendor/bin/sphpdox process "YourNameSpace" ./src -o ./docs/source
Это создаст каталог в ./docs/source/YourNameSpace
Использовать домен Sphinx PHP (который sphpdox использует), вы должны установить sphinxcontrib-phpdomain:
pip3 install sphinxcontrib-phpdomain
Теперь добавьте его в список расширений:
# ./docs/source/conf.py
extensions = [
# ...
"sphinxcontrib.phpdomain"]
Теперь вы можете ссылаться на сгенерированный каталог в вашем индексе сфинкса:
# ./docs/source/index.rst
.. toctree::
YourNameSpace/index
И чтобы сгенерировать вывод с помощью компоновщика, теперь запустите make [builder] (например. make html)
Чтобы автоматически генерировать файлы PHP reST при запуске компоновщика, вы можете изменить Makefile:
# ./docs/Makefile
php:
@../vendor/bin/sphpdox process "YourNameSpace" ../src/ -o ./source
%: php
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Другие решения
Других решений пока нет …