DevOps for documentation

Automatically testing and deploying documentation using a CI/CD pipeline

When we deploy documentation using a CI/CD Pipeline, we can run automatically run test scripts over our documentation and then define where and in what format we want it to go.

For example, if we have SMEs directly updating content, we run readability scripts over their proposed content automatically to ensure that it complies with plain English principles - alerting a technical writer if not. Of course we will double check this during a review cycle, but this allows to iteratively build content from several authors.

If the build passes, we can then deploy the document directly to the webpage of our choice - along with a PDF generated directly via the pipeline.

For example

  stage: build                          # This stage builds the document with the most recent content.
  image: sphinxdoc/sphinx-latexpdf      # In this example our document is a Sphinx document
    - pip install sphinx-rtd-theme
    - python  # We could add any number of text analysis functions here
    - make html                         # Generate the webpage output
    - make latexpdf                     # Generate the PDF output
    - mv _build/latex/*.pdf _build/html/$CI_PROJECT_NAME.pdf
      - _build/html

  stage: deploy                         # This stage deploys the documentation following successful build stages.
    - mkdir public
    - mv _build/html/* public           # This is where we want to send our document
    - public