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.

Links¶

reStructuredText¶

Introduction:	http://docutils.sourceforge.net/docs/user/rst/quickstart.html
Demo:	http://docutils.sourceforge.net/docs/user/rst/demo.html
Reference:	http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
Cheatsheet:	http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt

Sphinx¶

Main:	http://www.sphinx-doc.org
Introduction:	http://www.sphinx-doc.org/tutorial.html
Configuration:	http://www.sphinx-doc.org/config.html
Hosting:	https://readthedocs.org

UTF-8 with BOM?¶

The Includes.rst files, that are shipped to get started, suggest:

-*- coding: utf-8 -*- with BOM.

Actually the tools today manage UTF-8 well without BOM. I simply don’t bother about and everything works fine. For sure UTF-8 is the encoding of choice for almoust everything today.

Publishing TYPO3 Extension Documentation on Readthedocs¶

Your documentations gets it’s own subdomain like this:

http://typo3-extension-ehfaq.readthedocs.org

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.