Automatically building drafts 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: ```python 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. ```yml ... 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 ... ```
2 minute read | Concept

Automatically building drafts

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.

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
...
See also
DevOps for documentation

Home | Contact