sphinxcontrib-phpdomain
sphinxcontrib-phpdomain copied to clipboard
markstory
PHPDOC import
This is a feature request that would automatically import PHPDOC from library sources to avoid duplication between .rst and .php files.
- specify where source files are located.
- sources parsed during build
- comments are automatically imported.
Example source:
/**
* Collection of cool methods
*/
class CoolClass {
}
rst:
.. php:class:CoolClass::
Use CoolClass 3 times a day
Result:
class CoolClass
Collection of cool methods
Use CoolClass 3 times a day
Sounds cool. I don't really have time to build something like that right now so any help is appreciated.
I would do it, but my python skills would leave me strangled. 🐍
I found this library extremely useful: https://github.com/avalanche123/doxphp. Is it possible to execute that from sphinx or at least consume JSON output provided?
@markstory do you think this enhancement is viable at all? I can try looking for some help.
The python documentation tools, have autodoc. This sounds like it would be similar to that, so it is viable, but also a non-trivial amount of work.
We have done some prior art here: https://github.com/rtfd/sphinx-autoapi/ -- that is basically a standard framework for building language-specific doc tool importers for Sphinx/RST. It is definitely beta status, but might be a good place to steal ideas from.
Another bit of prior art is here: https://github.com/erikrose/sphinx-js/
There's also a good article on PHP here: https://www.sitepoint.com/using-sphinx-for-php-project-documentation/ -- but I don't believe it covers the source -> rst transform.
We are also currently developing this feature within our TYPO3 screenshot and code documentation tool.
https://github.com/TYPO3-Documentation/t3docs-screenshots/pull/234
