Getting started with Sphinx-Doc

Sphinx-Doc is a tool to generate a full html documentation from reStructuredText files.

To explain the reasons for switching to Sphinx, we describe the previous documentation. The previous documentation has been using the Gitlab wiki pages. As a consequence, the documentation is spread over all repositories of the project. Since some parts of the backend project also are interesting for the front-end teams, these chapters were moved to the common repository. This and some further cases made it unintuitive and complex to identify the location of certain information. Furthermore, there has been redundant documentation articles for shared tools in several repositories. The redundancy increased the effort for maintenance and limits the scalability for the documentation in future.

To solve all these problems, we decided to implement a unified documentation which can be looked up at one certain place. This is our new Sphinx documentation.

Setup local development environment

Attention

We recommend to use a Linux WSL or a Linux System. Furthermore, we recommend to use Ubuntu. However, the use of another distribution might lead to some adaptions regarding the installation and configuration of some plugins.

1. Setup Visual Studio Code for remote development on WSL

We recommend to follow the official guide from Microsoft.

2. Check Python3 & Pip3 Installation

Verify that you have Python3 and pip3 installed on your system.

3. Clone the Common repository and open the project in VSCode

4. Install the recommended plugins, or only the plugin restructuredText by lextudio.

5. Install Sphinx and some additional extensions

To use the reStructuredText Live Preview we need to install Sphinx and its autobuild extension. Refer to the plugins official documentation.

# Install Sphinx and the autobuild extension
pip install sphinx sphinx-autobuild

To compile the Sphinx plugin from the repository using the environment which is used in the deployed version, we further need to install a few extensions and a theme.

# Install theme and further extensions
pip3 install sphinx-rtd-theme sphinxcontrib-contentui sphinxcontrib-plantuml sphinxemoji sphinx_copybutton

The sphinx-rtd-theme extension gives our documentation the look and feel of a ReadTheDocs documentation. Refer to its its official documentation for more information.

The sphinxcontrib-contentui extension adds tabs, columns and collapsable headers. Refer to its its official documentation for more information.

The sphinxcontrib-plantuml extension adds support for generating models and graphs using the PlantUML Syntax. Refer to its its official documentation for more information.

The sphinxemoji extension adds support for Github emojis. Refer to its its official documentation for more information.

How to add a new article?

Before adding an article, we assume there is an issue that collects important details about the article. We will further assume, that you already cloned the repository and checked out the branch for the previously mentioned issue.

The first step for writing an article is to determine the goal of the article. What is the message you want to tell your audience? What is the purpose for the article? As you can see in the first question, the audience also is an important aspect of your article. Identify your audience to get aware of their language and knowledge. Do you write an article towards students with a computer science background or more to a customer from an older generation who does no use the fanciest words. These two aspects build the fundament for your article.

Next create a mindmap or a list to collect all ideas and important aspects for your article. You can start with a rough list and refine it in several steps. Make sure, that your audience understands each aspect listed. If you are unsure, refine that aspect. After the collection is finished, create a storyline. Sketch sections and assign each aspect to a single section. If you assign an aspect twice, it is likely that you will repeat yourself. Keep your article DRY (“Don’t Repeat Yourself”).

If your story and the structure is ready to go, start with your first draft. Do not mind to make mistakes. Also do not think too much about the wording at that point. To get a glance on the final rendered article, click on PREVIEW_BTN in the top right corner of VS Code to activate live rendering. The live rendering compiles the sphinx documentation and generates a HTML documentation in the build folder under the Sphinx root folder. Do not worry about versioning. The build folder will be ignored by git if its is under this path. The rendered page for you article will be loaded in a seperate tab.

After your first draft is written, read it again. This is called “editing”. Maybe try to read it loudly. What cannot be told fluently, also my be hard to read. Identify these sentences and revise them. Also check for clarity, ease to read, and comprehensibility. Is every term or concept explained? Do you use domain specific language which might not be understood by your audience? Do not forget to check for typos, contradictions or grammar mistakes. Therefore, it is necessary that your read your final article at least twice.

Important

Generate text first, then revise while editing and reviewing!

After the final draft is completed, let other people review the article. Collect the feedback, and revise your article. Furthermore, get aware of the feedback. Consider, which formulation or mistake lead to the critic. Make yourself also aware for the formulations which were great. The feedback is your chance to reflect and learn! Writing is a time-consuming activity which needs a lot of time and articles to be mastered. Do not underestimate the time it needs to write a good article.

When your article succesfully leaves the review stage, it can be merged to the final documentation. Good luck and have fun writing. 🙂 🍀