Is source code documentation dead? SitePoint's RTDSphinx-PHP says otherwise!

Documenting source code is hard stuff. Not just writing the actual words, but also doing it right. The documentation needs to be clear, intuitive, developer and user friendly and easy to modify so you can accept community contributions. What’s more, it’d be pretty cool if it was available in more than one language, so that certain developer communities don’t feel isolated.

We have things like PhpDocumentor and ApiGen, but those produce docs that are too technical and hard to read. It’s also quite difficult to add prose into them - you know, little snippets of code and mini-tutorials above methods and classes that demonstrate their use, as opposed to just describing their parameters and return values.

This is what we aim to fix, in at least some regard, by releasing RTDSphinx-PHP, a skeleton for Sphinx-generated documentation that’s multi-language by default, has PHP support built in on many levels, and is tweaked for publishing on ReadTheDocs, if the developer so desires - complete with customizable CSS styles for that personal touch.

This skeleton project is the first in a line of many SitePoint-branded projects we intend to release in the future. Most will be open source, and we’ll be welcoming contributions from everyone. We’ll also recognize our top contributors in articles pertaining to those projects, as well as offer some nifty badges for you to win, depending on how much you contribute!

The RTDSphinx-PHP skeleton and its usage are described in detail in this post, and is ready for use today. Go forth and check it out, then let us know what you think! And if you feel like you have the knowhow necessary to modify ApiGen, PhpDocumentor, Sami or Sage to produce PHPDomain-compliant .rst files for use with this skeleton, all the better - get in touch and we’ll work it out!

This topic was automatically closed 91 days after the last reply. New replies are no longer allowed.