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/automatically-building-drafts.html
Using a CI/CD pipeline and Git to produce timestamped draft PDFs and docx files
One of the tricky things when collaborating on documentation as a large and distributed team is controlling draft versions. We can rely on a pipeline to automatically generate and deploy time/commit stamped drafts. These drafts are always up-to-date with the most recent content and when receiving drafts back from SMEs, we can easily 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 is 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.
To implement 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 in order to rename the automatically generated documents.
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
...