Fast Multi-language Docs with SitePoint’s RTDSphinx-PHP

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. This guide will not be a “let’s build it from scratch” project, but rather an overview of the features this skeleton project offers out of the box, and an introduction into its usage.

This post will be the first in a long line of many SitePoint branded projects meant for wide-spread public consumption, fully open source and highly welcoming of other people’s contributions.

Quickstart

For prerequisites, make sure you have Python and pip, the Python package manager, installed.

First, clone the skeleton into a folder - either a subfolder of your project, like projectRoot/docs or into its own folder - anything goes.

git clone https://github.com/sitepoint/rtdsphinx-php docs

Optionally, create a Python virtual environment.

Then, while inside the cloned folder, install prerequisites from the requirements.txt file by running:

pip install -r requirements.txt

This will install all necessary packages.

That’s it. To generate files for a new language, run:

bin/update.sh xx

… where xx is the language code (e.g. “jp” for Japanese).
Then, edit files in locale/xx/LC_MESSAGES that end in .po.

To compile the HTML from these translations, run:

bin/build.sh xx yy zz

… where xx, yy and zz are language codes for all the languages you want to build. Inspect your generated HTML by opening _build/html/xx/index.html in a browser.

For deploying to ReadTheDocs, see below.

Continue reading %Fast Multi-language Docs with SitePoint’s RTDSphinx-PHP%

by Bruno Skvorc via SitePoint