PHPDOC import

[romaninsh]

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

[markstory]

Sounds cool. I don't really have time to build something like that right now so any help is appreciated.

[romaninsh]

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?

[romaninsh]

@markstory do you think this enhancement is viable at all? I can try looking for some help.

[markstory]

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.

[ericholscher]

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.

[linawolf]

We are also currently developing this feature within our TYPO3 screenshot and code documentation tool.

https://github.com/TYPO3-Documentation/t3docs-screenshots/pull/234