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.
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:
xx is the language code (e.g. “jp” for Japanese).
Then, edit files in
locale/xx/LC_MESSAGES that end in
To compile the HTML from these translations, run:
bin/build.sh xx yy zz
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%