Example: Docs as Code with Sphinx
Docs-as-code (also known as "Documentation as Code") refers to the concept of treating documentation as a codebase, i.e. integrating the documentation process in the toolchains and workflows used by software development teams.
Docs-as-code involves using version control systems such as Git for your documentation projects and authoring your content with plain text markup languages such as Markdown or reStructuredText, among other things.
To find out more about docs-as-code, head over to its website.
Whether you are a single technical communicator or a member of a larger documentation team, you can perfectly apply the docs-as-code approach to your documentation projects.
Initially developed to generate Python documentation, Sphinx is now widely used by technical communicators and software developers to create technical and software documentation.
Sphinx uses reStructuredText as a markup language to generate documentation content. Among further advantages, Sphinx allows you to produce your documentation in different formats, including HTML, LaTeX and ePub. You can also use one of the multiple extensions developed by the community to extend its functionality.
To begin setting up your project, you will first need an account on Codeberg. If you don't already have one, follow the instructions provided under Your First Steps on Codeberg.
This guide assumes that you already have Git installed on your machine. If you don't, you can install git as described in the article Install Git.
For the purpose of this guide, we will start a documentation project from scratch using an empty repository. To create a new empty repository and clone it to your local workspace, follow the steps described in the article Your First Repository as well as the instructions provided under "Option A: Clone the newly created, empty repository" within the same article.
A "virtual" isolated environment comes in very handy to eliminate the risk of any broken dependencies while working on your projects. In other words, setting up a virtual environment for your project allows you to run an instance of the Python interpreter with a particular package set and a specific configuration while ensuring compatibility between all these components inside that environment.
Before starting, you should make sure that you have pip and Python 3 installed on your machine. To check, type the following commands in your terminal:
$ pip --version
$ python3 --version
Depending on your Python version, you will need to install a compatible virtual environment manager, i.e. either "venv" for Python >= 3.3, or "virtualenv" for older Python versions.
Please note that Python2 has reached its EOL (End of Life) on January 1st 2020, which means that it is no longer receiving any security updates. If you are using Python 3.3 or higher, you do not need to install the "venv" module, since it is already available in your Python standard library.
The next step is to create a virtual environment. To do so, navigate to the folder where you have cloned the repository described under the section Setting up the project:
$ cd ~/repositories/foobar
$ python3 -m venv env
You can replace the second argument "env" with any other name your like. This will be the folder hosting your virtual environment.
.gitignorefile to exclude your virtual environment directory from your version control system. To ignore the entire "env" folder, include the corresponding path and append a
/at its end, e.g.
Before you begin performing any tasks on your project, you must activate your virtual environment by running the following command:
$ . env/bin/activate
To make sure that you are working inside of your virtual environment, run the command:
$ which python
The output of the command above should be the
env folder, e.g.:
When you are done working on your project, run the following command to leave the virtual environment:
If you have followed the steps described up to this point, your local repository should now contain your virtual environment's folder
env in addition to the hidden
.git directory and the
.gitignore file that we have already described at the end of the section Creating a Python virtual environment, e.g.:
├── myproject │ ├── env │ ├── .git │ └── .gitignore
$ mkdir mydocs
$ cd mydocs
Running the command
tree -a should now output the following:
With your virtual environment activated as shown above, it is now time to install Sphinx with
pip. To do so, run the following:
(.venv) $ pip install -U sphinx
If you wish to learn about the different options of
pip installare, run the command
pip install -h.
Once Sphinx is installed on your virtual environment, type the following command in your terminal:
(.venv) $ pip sphinx-quickstart
You will then be asked to answer a series of questions regarding the configuration of your project.
Confirm that you want to
Separate source and build directories. For the rest of the questions, keep pressing Enter to accept the default values and fill out the requested fields until you reach the question
autodoc: automatically insert docstrings from modules, then choose "y" (yes). Keep pressing Enter again until you reach the question
Create Makefile? and select "y" (yes).
If you now run the
tree command from your
mydocs folder, you should get the following output:
Congratulations! 🎉 You have just finished installing Sphinx on your Linux machine.
To set up a local testing server for your documentation project, you can use the Python module
http.server. To do so, you will first have to build the HTML resources for the initial test by running the command:
(.venv) $ sphinx-build -b html docs/source/ docs/build/html
Then navigate to the directory hosting the HTML resources:
(.venv) $ cd docs/build/html
Once there, run the local python server with the command:
(.venv) $ python3 -m http.server 8080
"8080" is the TCP port on which the host server is listening for requests.
To access the default
index.html file, type
http://localhost:8080 in your favorite browser. You should then see the default welcome page.
You can start creating your own content by making a new reStructuredText file (.rst) in the source directory:
(.venv) $ cd mydocs/source
(.venv) $ touch mynewfile.rst
You have just created an empty ".rst" file with the
touch command. An ".rst" file is simply a plain text file that is written with reStructuredText as a markup language. To learn about how to use reStructuredText, follow the instructions provided in the article reStructuredText Primer.
You will be more productive in your writing if you use a text editor that supports syntax highlighting such as Emacs or Atom. Linux offers plenty of powerful text editors that support syntax highlighting and other advanced features for coding and authoring tasks.
Whenever you create a new .rst file, you must add it manually to the
toctreeof your root document, i.e. "index.rst".
The toctree directive (toc stands for Table of Contents) inserts a tree that connects the different ".rst" files located in your source directory with each other. Read the article Directives to learn more about the toctree directive.
Once you have added an .rst file to the
toctree, you can check the output at any time by running the sphinx-build command illustrated above, then refreshing your local testing server.
If you are satisfied with the result on your local development environment, you can publish the content on Codeberg Pages. To find out how to do this, read the article Pushing output from SSGs into Codeberg Pages.
Hey there! 👋 Thank you for reading this article!
Is there something missing, or do you have an idea on how to improve the documentation? Do you want to write your own article?
For an introduction on contributing to Codeberg Documentation, please have a look at the Contributor FAQ.
© Codeberg Docs Contributors. See LICENSE