Automatically building drafts

Controlling draft versions remains one of the tricky things when collaborating on documentation as a large and distributed team. We can rely on a pipeline to automatically generate and deploy time/commit stamped drafts. These drafts then stay up-to-date with the most recent content and when receiving drafts back from SMEs, we can then track the changes.

SMEs can navigate at any time to our draft online environment and download a draft PDF or DOCX that we stamp with our Git commit number.

This proves useful for situations where our SMEs don't use a documentation generator and prefer to use traditional tools such as DOCX or commenting on PDFs.

For this, we add a variable to our Sphinx conf.py file that fetches the latest commit number. We then add a runner variable to our pipeline file to rename the automatically generated documents.

Example

In our conf.py file:

commit_id = commit_id = subprocess.check_output(['git', 'rev-parse', '--short=8', 'HEAD']).strip().decode('ascii')
commit_date = subprocess.check_output(['git', 'log', '-1', '--date=format:%Y-%m-%d %H:%M UTC', '--format=%ad', 'HEAD']).strip().decode('ascii')

html_context = {
    "commit_id": commit_id,
    "commit_date": commit_date,
}

# In our document, we can now use |commit_id| and |commit_date| to stamp the document.

In the pipeline file, use $CI_COMMIT_SHORT_SHA as the commit variable.

...
script:
  - sphinx-build -b singlehtml -D release=dev . _build/singlehtml # To build our draft docx
  - cd _build/singlehtml && pandoc index.html -o index.docx && cd ../../
  - mv _build/singlehtml/index.docx _build/html/$CI_PROJECT_NAME-$CI_COMMIT_SHORT_SHA.docx
  - sphinx-build -b latex -D release=DRAFT . _build/latex # To build our draft PDF
  - cd _build/latex && make && cd ../../
  - mv _build/latex/*.pdf _build/html/$CI_PROJECT_NAME-$CI_COMMIT_SHORT_SHA.pdf
...