The Neos documentation workflow

Neos (like the Flow Framework) is documented using the reStructuredText format and the Sphinx documentation renderer.
Using Sphinx everyone can render reStructuredText to HTML (and other formats), and we use the web-based readthedocs.org platform to generate rendered documentation for Neos and Flow.

This page explains how writing documentation works from a technical perspective.
If you have feedback, please get in touch with us!


You want to improve existing documentation

It is great that you want to help with improving the documentation of Neos or Flow! To get you started, here is an introduction into the most important things you need to know.

Workflow

Neos is made of a number of independent packages. Thus documentation is partly spread over those packages as well.

The documentation for Neos and Flow is contained in the Neos and Flow packages itself. There are other packages that have their own documentation (like the SEO addon or the Google Analytics integration). If you check the Documentation Library you will see that those are all rendered on readthedocs.org. They show up in the library because they are all maintained by the neos user there.

Editing documentation

You can just clone any package you want to contribute to and start editing the reStructuredText sources in the Documentation folder.

To check the results you can install Sphinx (see below on this page) and in the Documentation folder call make html to generate HTML output for you to check. If you run make livehtml you can even point your browser to http://127.0.01:8000 and see the updated documentation reload automatically when you change the sources.

If you are satisfied, create a nice commit and push it for review. Once it is merged, it will show up in the rendered documentation soon.

Communication

In our community platform we have created a category to discuss documentation related issues. Make yourself heard!


You want to add documentation

A great package deserves excellent documentation! To make your life easier this section shows you how to add documentation to a package.

Workflow

The documentation for Flow packages is contained in the package itself, inside the Documentation folder.

If you check the Documentation Library you will see that our "official" packages are all rendered on readthedocs.org. They show up in the library because they are all maintained by the neos user there.

If you want to have your own documentation rendered publicly, the easiest way is to create an account at readthedocs.org (it's free!) and import your project there.

Adding documentation

The minimal structure needed for documentation is an index.rstfile to put content into. Most of the time you also want to render that into HTML, so you need a conf.py file to tell Sphinx how to handle that. Having some extra directories to hold (potential) assets is the icing on the cake.

The easiest way to create that skeleton if you lack it, is to use the Kickstarter: ./flow kickstart:documentation

Editing documentation

You can just start editing the reStructuredText sources in the Documentation folder of your package.

To check the results you can install Sphinx (see below for some hints) and in the Documentation folder call make html to generate HTML output for you to check. If you run make livehtml you can even point your browser to http://127.0.01:8000 and see the updated documentation reload automatically when you change the sources.

If you are satisfied, create a nice commit and push it for review. Once it is merged, it will show up in the rendered documentation soon.

Communication

In our community platform we have created a category to discuss documentation related issues. Make yourself heard!


Installing Sphinx

Sphinx is the documentation renderer which we use to turn our .rst files into readable HTML documents. It is written in Python and therefore requires you to have the language installed. To install Sphinx with pip, run:

pip install sphinx

You might receive an error message along the lines of "ImportError: No module named sphinx_rtd_theme". If this comes up, install the theme:

pip install sphinx_rtd_theme

If you want to use make livehtml, you need to install sphinx-autobuild as well:

pip install sphinx-autobuild

For more detailed installation instructions and support regarding Sphinx, please refer to the Sphinx manual.