David Image

Technical Documentation Template Improvements

After working a contract the last few months, I've made several improvements to my working template.

I bundled several feature updates into the template as I had another working version at my previous company.

  • Replaced templating engine Cruft with Copier due to a simpler structure and more powerful scripting support.

  • Added a local LLM language processing script to integrate into publishing pipelines:

    process_compare_example

  • Replaced the heavy LaTeX PDF builder with lighter Weasyprint whilst keeping the critical Math functions:

    math_example

  • Added ISO warning directives:

    iso-warning-examples

  • Added a docx builder to mimic the PDF layout and facilitate reviews with non-technical contributors.

  • Improved handling of multi-document repositories, allowing companies to produce documentation packages.
  • Switched the package manager from pip to conda and created a supporting Docker image for publishing pipelines egamidocs/documentation-docker. This was primarily due to needing to install Weasyprint without local administration rights.

The template

Access the template below via GitLab. See source Sphinx documentation for more information on amending the template style.

egamidocs/technical-documentation-template

Example

Technical Document Example

Quick-start

If you have existing knowledge of Git and Python. Otherwise, see the template's README for a step-by-step guide.

Create a document from the template:

pip install copier
copier copy --trust git@gitlab.com:egamidocs/technical-documentation-template.git <slug>

Install and activate the environment:

conda env create -f https://egamidocs.gitlab.io/documentation-docker/environment.yml
conda activate doc_tools

Build:

python _scripts/build_html.py