Using Sphinx for PHP Project Documentation - SitePoint (2023)

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.

Using Sphinx for PHP Project Documentation - SitePoint (1)

RTD is widely used in the industry. It hosts powerful docs such as Guzzle’s, PhpSpec’s and many more. It supports reST alongside MD (or, to be more accurate, MD alongside reST), which is a huge plus as RST files are more suitable for highly technical documents. It can be run locally and generate offline-friendly HTML files, but it can also compile from documentation source available online and and be automatically hosted as a subdomain of readthedocs.org.

That said, setting it up for a PHP project has some caveats, so we’ll go through a basic guide in this tutorial.

TL;DR

If you’re just looking for the list of commands to get up and running quickly:

sudo pip install sphinx sphinx-autobuild sphinx_rtd_theme sphinxcontrib-phpdomainmkdir docscd docssphinx-quickstartwget https://gist.githubusercontent.com/Swader/b16b18d50b8224f83d74/raw/b3c1d6912aefc390da905c8b2bb3660f513af713/requirements.txt

After the quickstart setup, to activate the theme and PHP syntax highlights run:

sed -i '/extensions = \[\]/ c\extensions = \["sphinxcontrib.phpdomain"\]' source/conf.pyecho 'import sphinx_rtd_themehtml_theme = "sphinx_rtd_theme"html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Set up PHP syntax highlightsfrom sphinx.highlighting import lexersfrom pygments.lexers.web import PhpLexerlexers["php"] = PhpLexer(startinline=True, linenos=1)lexers["php-annotations"] = PhpLexer(startinline=True, linenos=1)primary_domain = "php"' >> source/conf.py

To build HTML:

make html

or

sphinx-build -b html source build

The latter command supports several options you can add into the mix.

Sphinx Installation

ReadTheDocs uses Sphinx behind the scenes, and as such is a through-and-through Python implementation. To make use of it, we need to install several prerequisites. We’ll use our trusty Homestead Improved to set up a brand new environment for us to play in.

After the VM is set up, SSH into it with vagrant ssh and execute:

sudo pip install sphinx sphinx-autobuild

If you don’t have the command pip, follow the official instructions to get it installed, or just execute the following if on Ubuntu:

sudo apt-get install python-sphinx python-setuptoolssudo easy_install pip

These tools have now made the command sphinx-quickstart available.

Recommended Folder Layout

Generally, you’ll either have:

  1. the documentation in the same folder as the project you’re documenting, or…
  2. the documentation in its own repository.

Unless the documentation spans several projects or contexts, it is recommended it be in the same folder as the project. If you’re worried about bloating the size of your project when Composer is downloading it for use, the docs can be easily kept out of the distribution by being placed into the .gitattributes file (see here).

(Video) Pengantar CI

When we run the command sphinx-quickstart, it’ll ask us for the root folder of our docs. This is the folder into which all other subfolders regarding the docs will go. Note that this is not the project’s root folder. If your project is at my-php-project, the root of the docs will likely be in something like my-php-project/docs.

Next, Sphinx offers to either make a separate _build folder for the compiled version of the docs (e.g. HTML), while the sources will be in the root (defined in the previous step), or to make two folders under root: source and build, keeping the root clean. Feel free to choose whichever option you prefer (we went with the latter, for cleanliness and structure).

Follow the rest of the instructions to set some meta data, select .rst as the file extension, and finally answer “no” to all questions about additional plugins – those refer to Python projects and are outside our jurisdiction. Likewise, when asked to create make files, accept.

Custom Theme

Building the documents with the command make html produces the HTML documents in the build folder. Opening the documents in the browser reveals a screen not unlike the following:

Using Sphinx for PHP Project Documentation - SitePoint (2)

That’s not very appealing. This theme is much more stylish and modern. Let’s install it.

pip install sphinx_rtd_theme

Then, in the source folder of the docs root, find the file conf.py and add the following line to the top, among the other import statements:

import sphinx_rtd_theme

In the same file, change the name of the HTML theme:

html_theme = "sphinx_rtd_theme"

Finally, tell Sphinx where the theme is by asking the imported module:

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Building the docs with make html should now produce some significantly prettier HTML:

Using Sphinx for PHP Project Documentation - SitePoint (3)

Most themes follow the same installation procedure. Here is a short list. Hopefully, it’ll expand in the future.

Table of Contents

During the quickstart, a user is asked for the name of the master file (typically index). The master file usually contains little to no content – rather, it only holds directives.

A reST directive is like a function – a powerful construct of the reST syntax which accepts arguments, options, and a body. The toctree directive is one of them. It requires an option of maxdepth, indicating the maximum number of levels in a single menu item (e.g. depth of 2 is Mainmenu -> Submenu1 but not -> Submenu2).

After the option goes a blank line, and then a one-per-line list of include files, without extensions. Folders are supported (subfolder/filetoinclude).

.. Test documentation master file, created by sphinx-quickstart on Sat Aug 8 20:15:44 2015. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive.Welcome to Test's documentation!================================Contents:.. toctree:: :maxdepth: 2 overview quickstart

In the example above, Sphinx prints out Contents:, followed by an expanded version of the table of contents, i.e. a bulleted list of all headings found in the included documents. Additionally, many authors include extra information at the top of the master file to give a birds-eye overview of the library right then and there. See Guzzle’s.

The toctree definition in the master file will be automatically mirrored in the left ToC navigation bar.

Let’s grab the overview and quickstart files from Guzzle so that we don’t have to write our own. Put them into the root of the docs, and rebuild with make html.

The documentation should now appear, and the left ToC should be expandable with the little plus icons:

Using Sphinx for PHP Project Documentation - SitePoint (4)

For more information about the toctree directive and everything it can do to give you truly customized output, see here.

PHP Syntax

If we look at the quickstart document, we’ll notice that the PHP samples aren’t syntax highlighted. Not surprising, considering Sphinx defaults to Python. Let’s fix this.

In the source/conf.py file, add the following:

from sphinx.highlighting import lexersfrom pygments.lexers.web import PhpLexerlexers['php'] = PhpLexer(startinline=True, linenos=1)lexers['php-annotations'] = PhpLexer(startinline=True, linenos=1)primary_domain = 'php'

This imports the PHP lexer and defines certain code block language-hints as specifically parseable by the module. It also sets the default mode of the documentation to PHP, so that if you omit a language declaration on a code block, Sphinx will just assume it’s PHP. E.g., instead of:

.. code-block:: php use myNamespace/MyClass; ...

one can type:

.. code-block:: use myNamespace/MyClass; ...

After adding the above into the configuration file, a rebuild is necessary.

make html

This should produce syntax highlighted PHP sections:

Using Sphinx for PHP Project Documentation - SitePoint (5)

PHP Domain

Additionally, we can install the PHP domain.

Domains are sets of reST roles and directives specific to a programming language, making Sphinx that much more adept at recognizing common concepts and correctly highlighting and interlinking them. The PHP domain, originally developed by Mark Story, can be installed via:

sudo pip install sphinxcontrib-phpdomain

The extension needs to be activated by changing the extensions line to:

extensions = ["sphinxcontrib.phpdomain"]

Let’s try and make another reST file now, with a described PHP class so we can see how well the PHP domain does its magic. We’ll create source/class.rst, and add class to the index.rst file under all the others. Then, we’ll put the following into class.rst:

DateTime Class==============.. php:class:: DateTime Datetime class .. php:method:: setDate($year, $month, $day) Set the date. :param int $year: The year. :param int $month: The month. :param int $day: The day. :returns: Either false on failure, or the datetime object for method chaining. .. php:method:: setTime($hour, $minute[, $second]) Set the time. :param int $hour: The hour :param int $minute: The minute :param int $second: The second :returns: Either false on failure, or the datetime object for method chaining. .. php:const:: ATOM Y-m-d\TH:i:sP

If we rebuild, we get something like this:

Using Sphinx for PHP Project Documentation - SitePoint (6)

Note that without the PHP Domain installed, this screen would be empty.

This doesn’t look too bad, but it could be better. We’ll leave the styling for another day, though.

View Source

It is common for docs to include a link to their source files at the top, so that users can suggest changes, raise issues and send pull requests for improvements if they spot something being out of place.

In the configuration options, there is a flag to show/hide these source links. By default, they’ll lead to _sources/file where file is the currently viewed file, and _sources is a directory inside the build directory – i.e., all source files are copied to build/_sources during the build procedure.

We don’t want this, though. We’ll be hosting the docs on Github, and we want sources to lead there, no matter where they are hosted. We can do this by adding HTML context variables into the conf.py file:

html_context = { "display_github": True, "github_user": "user", "github_repo": project, "github_version": "master", "conf_py_path": "/doc/", "source_suffix": source_suffix,}

Be careful to add this block after the project definition, else you’ll get an error about the project variable not being defined. Putting this at the bottom of conf.py is generally a safe bet.

Using Sphinx for PHP Project Documentation - SitePoint (7)

ReST vs MD

For a quick and dirty intro to reST, see this, but also look into the custom markup added by the Sphinx team – these additional features help you get the best out of your documentation.

ReST has many more features than MD does, so for parity’s sake and an easier transition, here’s a great conversion guide and a one-for-one comparison of features neatly laid out in tabular format.

Adding MD

Sometimes, you may not be willing or able to convert existing MD documentation into reST. That’s okay, Sphinx can dual-wield MD/reST support.

First, we need to install the MD processing module:

sudo pip install recommonmark

We also need to import the parser into source/conf.py:

from recommonmark.parser import CommonMarkParser

Finally, we need to tell Sphinx to send .md files to the parser by replacing the previously defined source_suffix line with:

source_suffix = ['.rst', '.md']source_parsers = { '.md': CommonMarkParser,}

If we try it out by adding a file testmd.md into source with the contents:

# TestMD!We are testing md!## Second heading!Testing MD files.--- echo "Here is some PHP code!"

Rebuilding should now show the MD content as fully rendered – with one caveat. The syntax won’t be highlighted (not even if we put the code into a PHP code fence). If someone has an idea about why this happens and how to avoid it, please let us know in the comments.

Hosting on ReadTheDocs

Now that our documentation is ready, we can host it online. For the purpose of this demo, we create a repo of sample content at http://github.com/sitepoint-editors/samplesphinx-php.

To host the docs online, we first add a new project…

Using Sphinx for PHP Project Documentation - SitePoint (8)

The next screen asks for a connection with Github. After importing repositories, we click Create on the one we want to create an RTD project from and confirm some additional values which can all be left at default.

After a build successfully finishes, our docs should be live:

Using Sphinx for PHP Project Documentation - SitePoint (9)

Note: this check used to be required, but RTD seems to have fixed the issue and you can now use the same theme declaration both in the local version, and the live one.

Extensions on RTD

Earlier in this tutorial, we installed the PHP Domain for easier directive-powered PHP class descriptions. This extension is not available on ReadTheDocs, though.

Luckily, ReadTheDocs utilizes virtualenv and can install almost any module you desire. To install custom modules, we need the following:

  • a requirements.txt file in the repo somewhere
  • the path to this file in the Advanced Settings section of our project on ReadTheDocs

To get a requirements file, we can just save the output of the command pip freeze into a file:

pip freeze > requirements.txt

The freeze command will generate a long list of modules, and some of them might not be installable on ReadTheDocs (Ubuntu specific ones, for example). You’ll have to follow the errors in the build phases and remove them from the file, one by one, until a working requirements file is reached, or until RTD improve their build report to flag errors more accurately.

For all intents and purposes, a file such as this one should be perfectly fine:

Babel==2.0CommonMark==0.5.4Jinja2==2.8MarkupSafe==0.23PyYAML==3.11Pygments==2.0.2Sphinx==1.3.1sphinxcontrib-phpdomain==0.1.4alabaster==0.7.6argh==0.26.1argparse==1.2.1docutils==0.12html5lib==0.999meld3==0.6.10pathtools==0.1.2pytz==2015.4recommonmark==0.2.0six==1.5.2snowballstemmer==1.2.0sphinx-autobuild==0.5.2sphinx-rtd-theme==0.1.8wheel==0.24.0

After re-running the online build (happens automatically) the documented PHP class should be available, just as it was when we tested locally.

Troubleshooting

ValueError: unknon locale: UTF-8

It’s possible you’ll get the error ValueError: unknown locale: UTF-8 on OS X after running either sphinx-quickstart or make html. If this happens, open the file ~/.bashrc (create it if it doesn’t exist), put in the content:

export LC_ALL=en_US.UTF-8export LANG=en_US.UTF-8

… save and close it, and then load it with the command source ~/.bashrc. The error should now no longer show up.

Table of Contents does not display / outdated

Sometimes when adding new files to include into index.rst, the ToC in the left sidebar will be out of date. For example, clicking on a file that was built before the new file was added will show a ToC with the latest file’s heading missing. The cause of this is unknown but it’s easily fixed by forcing a full rebuild:

rm -rf build/make html

The first command removes the build folder’s contents completely, forcing Sphinx to regenerate everything on make html.

Build Failed

If your builds fail and you can’t discern the reason, explicitly defining the location of conf.py under Advanced settings in Admin sometimes helps.

Conclusion

In this tutorial, we learned how we can quickly set up a Sphinx documentation workflow for PHP projects in an isolated VM, so that the installations don’t interfere with our host operating system. We installed the PHP highlighter, configured the table of contents, installed a custom theme, went through some basic ReST syntax and hosted our docs on ReadTheDocs. In a followup post, we’ll focus on styling, documentation versions and localization.

Do you use another documentation writing workflow? If so, which and why? Any other Sphinx/RTD tips? Let us know!

FAQs

How do you use the Sphinx for Python documentation? ›

Follow the steps given below:
  1. Step 1: Sphinx-quickstart. Run the below command inside your docs folder sphinx-quickstart. ...
  2. Step 2: Editing conf.py file. Go to your conf.py file and uncomment line numbers 13,14 and 15. ...
  3. Step 3: Generating .rst files. ...
  4. Step 4: Including module.rst and generating html.

What is Sphinx Django? ›

Sphinx is a popular tool for documenting Python projects, including the ability to generate automatic documentation using docstrings in your source code.

Can Sphinx use Markdown? ›

Markdown and reStructuredText can be used in the same Sphinx project. Markdown doesn't support a lot of the features of Sphinx, like inline markup and directives. However, it works for basic prose content.

Is Sphinx only for Python? ›

This line of thinking makes sense, because Sphinx was created to document Python itself. Sphinx however, is a generic documentation tool that is capable of documenting any software project. The goal of Sphinx is to help you write prose documentation. Prose docs work great for any kind of software you are documenting.

How do I create a documentation for a Python project? ›

Build Your Python Project Documentation With MkDocs
  1. Demo.
  2. Project Overview.
  3. Prerequisites.
  4. Step 1: Set Up Your Environment for Building Documentation.
  5. Step 2: Create the Sample Python Package.
  6. Step 3: Write and Format Your Docstrings. ...
  7. Step 4: Prepare Your Documentation With MkDocs. ...
  8. Step 5: Build Your Documentation With MkDocs.
15 Jun 2022

What is a Sphinx project? ›

Sphinx is what is called a documentation generator. This means that it takes a bunch of source files in plain text, and generates a bunch of other awesome things, mainly HTML. For our use case you can think of it as a program that takes in plain text files in reStructuredText format, and outputs HTML.

What does Sphinx stand for? ›

The Great Sphinx at Giza, near Cairo, is probably the most famous sculpture in the world. With a lion's body and a human head, it represents Ra-Horakhty, a form of the powerful sun god, and is the incarnation of royal power and the protector of the temple doors.

Who uses sphinx? ›

Google Drive, Dropbox, Zapier, Google Chrome, and DevDocs are some of the popular tools that integrate with Sphinx. Here's a list of all 5 tools that integrate with Sphinx.

What is sphinx coding? ›

Sphinx is a powerful documentation generator that has many great features for writing technical documentation including: Generate web pages, printable PDFs, documents for e-readers (ePub), and more all from the same sources. You can use reStructuredText or Markdown to write documentation.

What languages does sphinx support? ›

Sphinx supports documenting code objects in several languages, namely Python, C, C++, JavaScript, and reStructuredText. Each of them can be documented using a series of directives and roles grouped by domain.
...
Other languages (C, C++, others)
  • Fortran,
  • Julia, or.
  • PHP.

What is Sphinx Markdown? ›

Markdown is a lightweight markup language with a simplistic plain text formatting syntax. It exists in many syntactically different flavors. To support Markdown-based documentation, Sphinx can use MyST-Parser.

What is Toctree Sphinx? ›

.. toctree is a Sphinx-defined directive in which you explicitly list documents whose TOCs will be listed out.

How do you install Sphinx extensions? ›

Basic Installation
  1. Install the package along with Sphinx. There are two ways to install the extension. Using pip: ...
  2. Add the extension to the list in your conf.py settings file for each project where you want to use it: # conf.py ... extensions = ['sphinxcontrib. ...
  3. Rebuild all of the HTML output for your project.

How do you use the Sphinx in Windows? ›

This tool is provided with all modern versions of Python. On Linux or MacOS, you should open your terminal and run the following command. On Windows, you should open Command Prompt ( ⊞Win - r and type cmd) and run the same command. After installation, type sphinx-build --version on the command prompt.

How do I know if sphinx is installed? ›

To verify that Sphinx is installed, run the sphinx-build command with the --help parameter.

Where is sphinx located? ›

The Great Sphinx of Giza, commonly referred to as the Sphinx, is a limestone statue of a reclining or couchant sphinx (a mythical creature with a lion's body and a human head) that stands on the Giza Plateau on the west bank of the Nile in Giza, Egypt.

How do you write a documentation code? ›

Best Practices for Writing Documentation:
  1. Include a README file that contains. ...
  2. Allow issue tracker for others.
  3. Write an API documentation. ...
  4. Document your code.
  5. Apply coding conventions, such as file organization, comments, naming conventions, programming practices, etc.
  6. Include information for contributors.
29 Jun 2022

What is the best documentation for Python? ›

Sphinx is far and away the most popular Python documentation tool. Use it. It converts reStructuredText markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages, and plain text. There is also great, free hosting for your Sphinx docs: Read The Docs.

How do I use pydoc? ›

You can access the interactive shell in pydoc using it's help function. In order to do this, launch your terminal, and enter the python interactive shell. Now, import pydoc and then use the pydoc. help() command to launch the interactive shell.

What is Sphinx needs? ›

Sphinx-Needs is an extension for the Python based documentation framework Sphinx, which you can simply extend by different extensions to fulfill nearly any requirement of a software development team. Sphinx-Needs allows the definition, linking and filtering of need-objects, which are by default: requirements.

What is a sphinx directive? ›

Directives in sphinx-lesson are actually the special case of the generic directive class called admonitions. Directives are used to set off a certain block of text. They can be used as an aside or block (e.g. exercise , instructor-note ).

What is Sphinx Linux? ›

Sphinx is a documentation generator written and used by the Python community. It is written in Python, and also used in other environments.

Why is it called the Sphinx? ›

The English word sphinx comes from the ancient Greek Σφίγξ (transliterated: sphinx) apparently from the verb σφίγγω (transliterated: sphingo / English: to squeeze), after the Greek sphinx who strangled anyone who failed to answer her riddle.

What does a sphinx look like? ›

What Did The Sphinx Look Like Originally? We've Recreated It For ...

Are there two sphinxes? ›

Ancient Egypt

Two sphinxes existed on the Pyramids Plateau, according to a study which was published in 2007 by Egyptologist Bassam El Shammaa. El Shammaa said the famed half-lion, half-man statute was an Egyptian deity that had been erected next to another sphinx, which has since vanished without a trace.

How did the Sphinx work? ›

Sphinx is what is called a documentation generator. This means that it takes a bunch of source files in plain text, and generates a bunch of other awesome things, mainly HTML. For our use case you can think of it as a program that takes in plain text files in reStructuredText format, and outputs HTML.

What does the Sphinx represent? ›

The Great Sphinx at Giza, near Cairo, is probably the most famous sculpture in the world. With a lion's body and a human head, it represents Ra-Horakhty, a form of the powerful sun god, and is the incarnation of royal power and the protector of the temple doors.

What does it mean to call someone a sphinx? ›

In Greek, sphinx means "the strangler.” If someone is like a sphinx, it just means they're mysterious and quiet, not that they'll strangle you.

What did the Sphinx do? ›

The Sphinx sat perched on a mountain cliff nearby the ancient city. The creature guarded Thebes with a riddle that she had learned from the Muses. Each time a traveler failed to solve her riddle, she devoured them, effectively preventing anyone from leaving or entering the city.

What is Sphinx needs? ›

Sphinx-Needs is an extension for the Python based documentation framework Sphinx, which you can simply extend by different extensions to fulfill nearly any requirement of a software development team. Sphinx-Needs allows the definition, linking and filtering of need-objects, which are by default: requirements.

What is Sphinx-build? ›

sphinx-build generates documentation from the files in <sourcedir> and places it in the <outputdir> . sphinx-build looks for <sourcedir>/conf.py for the configuration settings. sphinx-quickstart(1) may be used to generate template files, including conf.py . sphinx-build can create documentation in different formats.

What is a Sphinx directive? ›

Directives in sphinx-lesson are actually the special case of the generic directive class called admonitions. Directives are used to set off a certain block of text. They can be used as an aside or block (e.g. exercise , instructor-note ).

Are there two sphinx? ›

Ancient Egypt

Two sphinxes existed on the Pyramids Plateau, according to a study which was published in 2007 by Egyptologist Bassam El Shammaa. El Shammaa said the famed half-lion, half-man statute was an Egyptian deity that had been erected next to another sphinx, which has since vanished without a trace.

What does a sphinx look like? ›

What Did The Sphinx Look Like Originally? We've Recreated It For ...

Where is sphinx located? ›

The Great Sphinx of Giza, commonly referred to as the Sphinx, is a limestone statue of a reclining or couchant sphinx (a mythical creature with a lion's body and a human head) that stands on the Giza Plateau on the west bank of the Nile in Giza, Egypt.

Who uses sphinx? ›

Google Drive, Dropbox, Zapier, Google Chrome, and DevDocs are some of the popular tools that integrate with Sphinx. Here's a list of all 5 tools that integrate with Sphinx.

How do you use sphinx in a sentence? ›

(1) I've always found her rather sphinx - like. (2) The Great Pyramids and the Sphinx are nearby. (3) We set off to see the Pyramids and Sphinx. (4) The Sphinx could keep his secret, we decided.

What's the plural of sphinx? ›

Noun. sphinx (plural sphinxes or sphinges) (mythology) A creature with the head of a person and the body of an animal (commonly a lion).

Who built Sphinx? ›

The question of who built the Sphinx has long vexed Egyptologists and archaeologists. Lehner, Hawass and others agree it was Pharaoh Khafre, who ruled Egypt during the Old Kingdom, which began around 2,600 B.C. and lasted some 500 years before giving way to civil war and famine.

What is the origin of the Sphinx? ›

About 1600 bce the sphinx first appeared in the Greek world. Objects from Crete at the end of the middle Minoan period and from the shaft graves at Mycenae throughout the late Helladic age showed the sphinx characteristically winged.

Top Articles
Latest Posts
Article information

Author: The Hon. Margery Christiansen

Last Updated: 09/22/2022

Views: 5873

Rating: 5 / 5 (50 voted)

Reviews: 81% of readers found this page helpful

Author information

Name: The Hon. Margery Christiansen

Birthday: 2000-07-07

Address: 5050 Breitenberg Knoll, New Robert, MI 45409

Phone: +2556892639372

Job: Investor Mining Engineer

Hobby: Sketching, Cosplaying, Glassblowing, Genealogy, Crocheting, Archery, Skateboarding

Introduction: My name is The Hon. Margery Christiansen, I am a bright, adorable, precious, inexpensive, gorgeous, comfortable, happy person who loves writing and wants to share my knowledge and understanding with you.