Overview

Teaching: 5 min
Exercises: 0 min

Questions

• What is the documetation artifact and what does CI/CD look like for this?

Objectives

• Figure out the CI/CD for documentation

Next, we will discuss another artifact from software we can setup CI / CD for: container images!

Documentation artifacts

In our example repository, we have our documentation source code in docs/.

Using sphinx, you can “build” the documentation. Similar to our Python package, the output of the documentation build is an artifact. Yet, it is not an installable package that we output.

Action: What are the artifacts for documentation?

When you access documentation for some of your favorite softwares, what form is it in? Which is your favorite form of documentation?

Examples

• Websites, like on [ReadTheDocs][rtd] (example: NumPy docs)
• PDF files (example: RMCProfile v6.7.4 docs)
• API documentation like [Swagger / OpenAPI][openapi] for Software-as-a-Service (example: Arcsecond Swagger or GitHub REST API docs)

What do we want from CI/CD for Sphinx documentation?

Sphinx will allow for multiple output formats (i.e. PDF or website).

Arguably, the website format is the favorite. For this, Sphinx can generate HTML files that can be used to create a [static webpage][static-page]

As we discussed in the first episode, we can use CI / CD for all sorts of stuff. We just need to ask the questions:

• “What workflow am I trying to automate?”
• For CI: “What does ‘breaking changes’ mean for my workflow?”
• For CD: “What does deployment / delivery / release mean for my workflow?

Action: Answer these questions for our documentation workflow

Considering we use sphinx to create files and want a documentation webpage, what are your answers to the questions above?

• For CI, what will we automate and check for documentation?
• For CD, what will we be deploying for documentation?

Solution

• For CI: we want to automate building the documetation HTML files
• For CD: we want to automatically publish the artifact for the static webpage and, eventually, deploy it onto a web server.

For documentation CI/CD, we do need to think about the end goal.

Basically, if we aren’t using services like [ReadTheDocs][rtd], we need to run a web site on a web server.

So the HTML files could be considered the final artifact. Yet, there is a “nicer” solution for software artifacts that have gained immense popularity do to their ease of deployment and reproducibility!

To be revealed in the next episode…

Key Points

• Documentation and website artifacts are different than package artifacts