DevOps for documentation

DevOps for documentation Automatically testing and deploying documentation using a CI/CD pipeline When we deploy documentation using a [CI/CD Pipeline](https://semaphoreci.com/blog/cicd-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 multiple 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. ```yaml build: 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 before_script: - pip install sphinx-rtd-theme - python spellcheck-readability.py # We could add any number of text analysis functions here script: - make html # Generate the webpage output - make latexpdf # Generate the PDF output - mv _build/latex/*.pdf _build/html/$CI_PROJECT_NAME.pdf artifacts: paths: - _build/html pages: stage: deploy # This stage deploys the documentation following successful build stages. script: - mkdir public - mv _build/html/* public # This is where we want to send our document artifacts: paths: - public ```

We electronically control revisions for this topic and deploy it directly online. Any copies you generate from the latest revision are uncontrolled. Ensure you refer to the latest revision online when possible.

Latest revision: /docs-as-code//2020/12/04/devops-for-documentation.html

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 multiple 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.

Example

build:
  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
  before_script:
    - pip install sphinx-rtd-theme
    - python spellcheck-readability.py  # We could add any number of text analysis functions here
  script:
    - make html                         # Generate the webpage output
    - make latexpdf                     # Generate the PDF output
    - mv _build/latex/*.pdf _build/html/$CI_PROJECT_NAME.pdf
  artifacts:
    paths:
      - _build/html

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

DevOps for documentation

Example

See also