Skip to content

docs-builder

Docs-builder is a tool for creating a single documentation site for docs that are spread across several repositories.
Docs-builder gathers documentation from other repositories as specified in a configuration file, builds any diagrams from PlantUML files and builds HTML from Markdown files with MkDocs, so that the documentation can be put together. We use it for our own internal documentation at OUS AMG. See how here

How to install and run

  • make build-image to build the Docker image
  • make all to run the other make targets (fetch-repos, build-diagrams, and build-docs).

Alternatively, you can do a manual install without Docker:
Given a Python >=3.x installation, install poetry (pip install poetry), and run poetry install to create a virtual environment with the necessary packages. For building diagrams, you also need to install PlantUML, which requires a Java Runtime Environment and Graphviz. You can get a jar-file with all dependencies (including Graphviz) by doing PLANTUML="https://github.com/plantuml/plantuml/releases/download/v1.2022.4/plantuml-1.2022.4.jar"; wget ${PLANTUML} -O plantuml.jar

Configuration options

There are two import configuration files for docs-builder, both can be found in config/:

  • docs-builder.json : Describes the repositories with docs and how to fetch them
  • mkdocs.yml : This file controls how MkDocs builds the HTML from the Markdown docs

The core of docs-builder is the Python application src/docsbuilder.py which performs different tasks depending on which command it is given.

  • fetch-repos clones all repositories according to configuration file
  • build-diagrams uses PlantUML to render any diagrams to e.g. SVG files, which can be linked to in Markdown
  • build-docs runs MkDocs, which builds HTML pages according to mkdocs.yml

docsbuilder.py takes several optional arguments, but has sane default values for most of them. Even the required config files have defaults, pointing to the ones in the config directory. If you do not use Docker, you probably want to point to your plantuml.jar file with --plantuml-path. By default, docsbuilder.py does not need any credentials. But if you want to clone private repositories, you can provide one username and token interactively (--ask-credentials) or supply up to several as arguments with --git-credentials. See docsbuilder.py --help for more information. By default, your built HTML files will be output under /tmp/mkdocs-tmp/public/. When using Makefile, the output path can be changed by setting the environment variable OUTPUT_DIR.

For each repo, docs-builder.json can take the following options

  • "directory_name" The name that will be used for the repo directory
  • "git" The git clone URL. HTTPS-protocol is recommended.
  • "skip_repo" Boolean to include this repo or not. [Optional]
  • "skip_paths" List of file/directory paths to skip. [Optional]