Tools

The use of development tools and workflows is a key requirement for the F5 docs-as-code strategy. We use the following tools to develop, test, review, and publish documentation.

Git

Git is an open source version control system. Our projects are developed in GitLab. Some projects may also have a corresponding public repo in GitHub.

GitLab provides a Web IDE that makes contributing easy without having to learn to use Git on the command line. For those who want to go the latter route, follow the instructions below and review the suggested training resources to get going.

Installation and Setup

  1. Install Git

    Getting Started - Installing Git

  2. Set up your global Git configs

    First-time Git setup

  3. Set up an account in GitHub (optional)

    GitHub - Account Setup and Configuration

See also

Git resources

Markdown and ReStructuredText

Plaintext markup languages like ReStructured Text (rST) and Markdown (MD) are standard in open source projects. Both are simple and easy to learn.

Documentation can use either Markdown or rST.

You can use any terminal text editor (vim, emacs, etc.) you’re comfortable with to work on the documentation. We recommend using an IDE/text editor with extensions that support MD and rST. Visual Studio Code and Sublime Text both integrate easily with GitLab and have extensions that support Markdown and rST.

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.

Component Projects

We have internally developed a few supporting projects that help provide a consistent user experience for both F5 employees and for our customers.

containthedocs

This is a docker image that has all of the required doc dependencies built in. This image is used for all CI/CD pipeline jobs to ensure a consistent environment across CI platforms. 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.

Docker users can build and test docs in a Docker container locally with the make docker-html, make docker-preview, and make docker-test commands.

If you want to just work in a Docker container, pull the containthedocs image from Quay and launch a container running the image:

docker login quay.pdsea.f5net.com -u <username> -p <password>
docker pull quay.pdsea.f5net.com/containthedocs:latest
./scripts/docker-docs.sh

Important

The docker run command contained in the script mounts the container to the current working directory. Changes you make in the container will affect your local files.

f5-sphinx-theme

The f5-sphinx-theme is an open source project developed in GitHub. It provides formatting consistent with F5 marketing/branding requirements to all of the F5 projects that use Sphinx to build documentation. All contributors are welcome!

Processes

Git Workflow

In general, the documentation should follow the same development workflow used by the engineering teams. This may vary somewhat from product group to product group. The basic workflow is:

  1. Check out a feature branch.
  2. Commit and push your work to GitLab.
  3. When ready, rebase against the master branch and squash your commits into a single commit. Push your work to GitLab.
  4. Open a merge request and tag reviewers.
  5. Add more commits to address the reviewers’ comments.
  6. Rebase and squash again.

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 merge requests to specific team members and/or @ mention team members in your merge request message.

Documentation Tests

We are developing a set of tests that check grammar, syntax, and spelling; check docs format against the defined templates; and more! Updates coming soon.

See the docs test jobs in the CI/CD pipelines for this repo for an example grammar and style check.

Docs Staging & Publication

Documentation publishes to GitLab Pages to ensure the security of Blue proprietary content. Updates coming soon.