Documentation or How to Use Sphinx

Intro

TYPO3 documentation is written using the Sphinx authoring system. A Sphinx repositiory consits of multiple related files that are written using the markup language reStructuredText. They derive from the programming language Python

... and yes, the rendering is done with a Python tool chain, not with PHP, but there are solutions, to present the Sphinx authored content within a TYPO3 generated page.

Examples

To see the reStructuredText source of this page click the link Page source in the bottom ot this page. You can do that on all pages here and even for most documentations hosted by Read the docs or docs.typo3.org.

My Standards

Inline

Code:
  • :code:`ls -al` => ls -al
  • :ts:`10.10 = FLUIDTEMPLATE` => 10.10 = FLUIDTEMPLATE
Title:
  • `HTML` => HTML
  • `Elmar Hinz` => Elmar Hinz
  • `TYPO3` => TYPO3
  • :title:`TYPO3` => TYPO3 (long form)
Literal:
  • ``127.0.0.1`` => 127.0.0.1
  • ``docker-compose.yml`` => docker-compose.yml
  • ``Error 505`` => Error 505
  • :literal:`Error 505` => Error 505 (long form)
Strong:
  • **bold** => bold
Stressed:
  • *italic* => italic

Text Blocks

Shell

.. code-block:: bash

# Be nice!
TYPO3=”cool”
echo $TYPO3
# Be nice!
TYPO3="cool"
echo $TYPO3

Python

.. code-block:: python

# Be nice!
TYPO3 = “cool”
print(TYPO3)
# Be nice!
TYPO3 = "cool";
print(TYPO3);

TypoScript - none

.. code-block:: none

page = PAGE
page.10 = TEXT
page.10.value = Hello world!
page = PAGE
page.10 = TEXT
page.10.value = Hello world!

There is no syntax highlighting for TS. In such cases none is the choice.

Publishing TYPO3 Extension Documentation on Readthedocs

Your documentations gets it’s own subdomain like this:

Tip

The subdomain is determined when you create/connect the project by the name you specify for it.

Why should I do that?

Well, your documentation is published on https://docs.typo3.org, isn’t that enough? Yes, it is enough. However, publishing to multiple channels may be better, especially if it can be done by a fully automated process.

Moreover, with every push the latest edit of your documentation is published immediately, long before you upload the extension to TER. You can direct those people, who like to use your latest version from Git, to the latest documentation.

Hint

The immediate availability of your edits may encourage you, to write more early and more often, side by side with your extension development.

The Concept

Nowadays there are a lot of services that support continuous integration (CI) of open sourced software, like the ecosystem around GitHub. GitHub and Read the Docs are well integrated. It’s a child game to set up the triggering mechanisms to automatically render the your documantiation whenever you push a change.

I use GitHub as an example. Other services git.typo3.org will provide similar triggers or you may consider a mirror on Github.

The Setup

The basic setup is easy-peasy. Obviously you need to register an account both on GitHub and Read the Docs. You set up a Git repository for your extension on GitHub, if you didn’t already. You fire up the web based administration on Read the Docs to connect it to your GitHub account. Once you have done that it will present you all your Github repositories. You select those, that contain a Sphinx documenation that you want to get shown on Read the Docs.

That’s all to get the triggering set up, but likely it will not successfully render your docs directly. Depending on your setup you have to do some tiny adjustments to get it running.

Tip

The main index file of the extension documenation is named Index.rst. Read the Docs want’s it lowercase, beacuse the server is configured to ship index.html as the index file. A symblic link does the tric.

ln -s Index.rst index.rst

Tip

The rendering configuration on docs.typo3.org requires a file named Settings.cfg while Read the Docs requires a file named conf.py. A little work, but you gain the option to provide different configurations for both.

Hint

See an example of conf.py. Running the sphinx-quickstart tool is a way to autogenerate that file. (Better use an empty directory.)

Tip

You select the theme by the parameter html_theme. Setting it to default will give you the Read the Docs standard theme. Alternatively you can selet one of Sphinx built in themes like alabaster or haiku. (How to set the theme of docs.typo3.org, will require your own research, to find out.)