Looking for more information on how to do PHP the right way? Check out PHP: The Right Way

SitePoint PHP Blog:
Fast Multi-language Docs with SitePoint’s RTDSphinx-PHP
Sep 09, 2015 @ 17:42:50

The SitePoint PHP blog has a tutorial posted showing you how to create multi-language documentation with ReadTheDocs and Sphinx with the help of the RTDSphinx-PHP library.

This post will guide you through getting up and running with RTDSphinx-PHP, a ReadTheDocs-friendly Sphinx based PHP documentation skeleton with sane defaults, pre-installed directives, and modified styles for optimal API and prose documentation rendering in multiple languages. For an unfinished example of the documentation, see here and switch the language in the bottom left flyout panel.

If this sounds familiar, it’s because we already went through a manual setup of a similar skeleton in a previous post, but that one had no localization support, too many steps, and wasn’t as reusable as this newly developed one.

He starts with the "quickstart" instructions to help you get the necessary tools installed to create the documentation. From there he gets into some of the main features the library provides including localization, a few utility scripts and syntax highlighting. Each of these comes with a bit of code/markup showing how to put them to use. The post ends with the instructions you'll need to push the documentation you've created up to ReadTheDocs and what the results should look like.

tagged: documentation multilanguage language readthedocs sphinx library

Link: http://www.sitepoint.com/fast-multi-language-docs-with-sitepoints-rtdsphinx-php/

SitePoint PHP Blog:
Using Sphinx for PHP Project Documentation
Aug 17, 2015 @ 14:19:04

The SitePoint PHP blog has posted a guide to using Sphinx, a documentation generation tool that's used behind the scenes for the ReadTheDocs hosted documentation service.

I recently had the need to write proper prose-like source-code documentation for the Diffbot PHP client. Having looked at several documentation generators, and even having suggested a @prose tag for importing of related MD/reST documents into method and class descriptions, I realized there simply is no perfect solution we can all agree on (yet). So until I extend Sage with a @prose token and reST parsing, I opted for ReadTheDocs and Sphinx.

He starts with a quick "TL;DR" of the necessary commands to get things working quickly but follows it with the full details. He walks you through the installation of Sphinx locally, setting up the folders and adding a custom theme. He show how to create the table of contents, activate the PHP syntax highlighting and how to show/hide the "Edit on GitHub" links. He also includes the steps to convert Markdown documents into the reST format and, finally, adding the project to the ReadTheDocs site and pushing your results.

tagged: sphinx project documentation tutorial readthedocs markdown rest

Link: http://www.sitepoint.com/using-sphinx-for-php-project-documentation/


Trending Topics: