Tools¶

The use of tools and practices commonly used in the open source community was a key requirement for the F5 open source documentation strategy. This requirement led to our selection of the following tools for producing, reviewing, and publishing documentation for open source projects.

Git¶

Git is an open source version control system. GitHub is a public git code-hosting platform used for open source development projects. GitLab is a git code-hosting platform used internally for proprietary private git projects. (GitLab provides the online GUI for both git and gitswarm projects.)

Using git isn’t a requirement per se, but some kind of version control is. Due to the collaborative nature of our projects, including documentation, it’s imperative that you have a way to ensure contributions from different sources are ‘safe’, resolvable, and traceable.

Installation and Setup¶

Install Git

Getting Started - Installing Git
Set up your global Git configs

First-time Git setup
Set up an account in GitHub

GitHub - Account Setup and Configuration
Install and set up GitHub Desktop

(Optional; good for those who prefer a GUI to working on the command line.)

ReStructured Text (rST)¶

Plaintext markup languages like ReStructured Text (rST) and Markdown are standard in open source projects. Both are simple and easy to learn. We opted for rST because of its more robust Sphinx functionality and de facto use in Python project documentation. The sphinx configurations (conf.py) included in this repository support both rST and MD.

Sphinx¶

Sphinx is a Python documentation generator. It’s an open source tool that was initially developed for the Python documentation and is the most commonly-used tool for generating Python project documentation.

While you can use Sphinx without knowing Python, a familiarity with Python can be beneficial. It allows you to move past the basic configurations and customize your documentation to meet your project’s specific needs.

Installation and Setup¶

The easiest way to install Sphinx is via pip, from this project’s requirements:
```
pip install -R requirements.txt
```
Copy the entire docs/ directory from this project to your project. You now have a Sphinx project!
Edit the docs/conf.py file to replace the generic ‘product’ information as appropriate for your project.

See also

First Steps with Sphinx tutorial.

containthedocs¶

We’ve developed a Docker image – containthedocs – that has all of the required doc dependencies built in. If you’re a Docker user and you don’t want to install the project doc requirements, you can build and test your docs in a Docker container with the make docker-preview and make docker-test commands, respectively.

If you want to just work in a Docker container, pulls the containthedocs image from Docker Hub and launches a container running the image

docker pull f5devcentral/containthedocs
./scripts/docker-docs.sh

This project also contains the scripts that make continuous deployment and staging possible. If you’re interested in contributing, fork the containthedocs project in GitLab.

Processes¶

Git Workflow¶

Use the git workflow that works best for your team. Be sure to establish a branching strategy as well. If you’re new to Git and/or version control in general, we recommend getting started with the GitHub Hello World tutorial.

Peer Review¶

Peer review is an essential part of any collaborative development workflow. Feedback from others – including constructive criticism – makes your contribution better. It helps you find incorrect or inconsistent details you may have overlooked; think about things from another person’s (or, user’s) perspective; and, perhaps, even learn something new. Assign pull requests to specific team members and/or @ mention team members in your pull request message.

Tip

For more information about how to conduct peer review in GitHub, see the excellent video How GitHub Uses GitHub to Document GitHub.

View Draft Documentation¶

We highly recommend building drafts of your documentation while you work on it. This makes it easier both to identify ‘bugs’ in your docs (for example, incorrect Sphinx syntax, inconsistent bullet or ordered lists, etc.) and to view your content from the user’s perspective.

The make html command builds the documentation set based on configurations included in the Makefile.

We also have a few custom commands that use sphinx-autobuild to provide a live preview of your documentation as you write it:

make preview - builds the documentation locally and serves it at 127.0.0.1:8000.
make docker-preview – builds the documentation and serves it from a Docker container running the containthedocs image.

This is particularly useful if you don’t want to install the sphinx project dependencies locally.

Test Documentation¶

The test-docs script runs make html to check the sphinx and rST syntax; make linkcheck to validate links; and write-good to check for common grammatical errors.