Development Guidelines for Documentation¶

The VAST Tools documentation has been developed using the python package mkdocsand the material theme. It is published as a static website using GitHub pages.

Documentation development server¶

This section describes how to set up a development server to live reload your changes to the pipeline documentation.

The main code of the documentation is located in the docs directory. In order to keep CHANGELOG.md, LICENSE.txt and CODE_OF_CONDUCT.md and the notebook examples on the repository root path, relative soft links have been created under the docs folder:

components
contributing
changelog.md -> ../CHANGELOG.md
code_of_conduct.md -> ../CODE_OF_CONDUCT.md
getting_started
gen_doc_stubs.py
img
index.md
license.md -> ../LICENSE.txt
notebook-examples -> ../notebook-examples
reference
scripts
theme

Start the development server from the root project directory (i.e. not inside the docs folder) by using the command:

(pipeline_env)$ mkdocs serve

By default this launches the server on the localhost port of 8008 and can be reached by entering into preferred browser the address:

localhost:8008

Files in the docs directory are then 'watched' such that any changes will cause the mkdocs server to reload the new content.

The structure of the site (see nav section) and the settings are in the mkdocs.yml in the root of the repository.

Plugins and Customisations¶

mkdocs and the material theme have a lot of customisations and plugins available. The more involved plugins or customisations that are in use for this documentation are detailed in the following sections.

Custom theme directory¶

The theme directory contains various overrides to the standard material template. This is enabled by the following line in the mkdocs.yml file:

theme:
  custom_dir: docs/theme

Custom javascript and css files are also stored in this directory and are enabled in the following mkdocs.yml file:

extra_css:
  - theme/css/extra.css
extra_javascript:
  - theme/js/extra.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

The contents of the theme directory are shown below:

docs/theme
├── assets
│   └── stylesheets
│       └── overrides.css
├── css
│   ├── extra.css
│   └── lightgallery.min.css
├── fonts
│   ├── lg.svg
│   ├── lg.ttf
│   └── lg.woff
├── home.html
├── img
│   └── loading.gif
├── js
│   ├── extra.js
│   ├── lg-zoom.js
│   └── lightgallery.min.js
└── main.html

Full documentation on customising the mkdocs-material theme can be found in the documentation.

main.html contains edits to the main.html as described in the documentation linked to above. The other files shown are used for the custom homepage and the Lightgallery.

Custom Homepage¶

The homepage is overwritten by a custom stylised HTML page. This is achieved using the following files:

docs
├── index.md
├── theme
│   ├── assets
│   │   └── stylesheets
│   │       └── overrides.css
│   ├── home.html
│   └── main.html

The index.md file in the main docs directory should only contain the following.

---
title: VAST Tools
template: home.html
---

Creation and Last Updated Dates¶

Each page displays a date of creation and also a "last updated" date. This is done by using the plugin mkdocs-git-revision-date-localized-plugin. The following options are used:

plugins:
  - git-revision-date-localized:
      fallback_to_build_date: true
      enable_creation_date: true

WARNING -  [git-revision-date-localized-plugin] Unable to find a git directory and/or git is not installed. Option 'fallback_to_build_date' set to 'true': Falling back to build date

Lightgallery¶

Images are displayed in the documentation using the lightgallery-markdown plugin. As described in the repository linked to above, certain assets from lightgallery.js are copied over to make the extension work, the files that apply here are:

docs/theme
├── css
│   └── lightgallery.min.css
├── fonts
│   ├── lg.svg
│   ├── lg.ttf
│   └── lg.woff
├── img
│   └── loading.gif
├── js
│   ├── extra.js
│   ├── lg-zoom.js
│   └── lightgallery.min.js
└── main.html

lg-zoom.js is also copied over to activate the zoom feature on the gallery images.

MathJax¶

MathJax is enabled as described in the mkdocs-material documentation.

mknotebooks¶

mknotebooks allows for Jupyter Notebooks to be incorporated into the documentation. No options other than the defaults are used, however, overflow is enabled on the output_wrapper div class through below entry in extra.css. This allows for pandas dataframes x-scrolling.

/* Add overflow to mknotebooks dataframes */
.output_wrapper {
  overflow: auto;
}

Python Docstrings and Source Code¶

Python docstrings and source code are rendered using the mkdocstrings plugin.

The markdown files for the docstrings are automatically generated using mkdocs-gen-files in the file docs/gen_doc_stubs.py. It is activated by the following lines in the mkdocs.yml file:

plugins:
  - search
  - gen-files:
      scripts:
      - docs/gen_doc_stubs.py

The markdown files are programmatically generated, this means that the markdown files don't actually appear, but are virtually part of the site build. The files must still be referenced in the nav: section of mkdocs.yml, for example:

- nav:
  - Code Reference:
    - vast_pipeline:
      - image:
        - main.py: reference/image/main.md
        - utils.py: reference/image/utils.md

The files are virtually created relative to the doc path that is stated in gen_doc_stubs.py. For example, using the vast_pipeline as the base for the python files and reference as the doc path, the markdown file for the docstrings in vast_pipeline/image/main.py is created at reference/image/main.md.

Please refer to the mkdocstrings documentation for full details of the options available to declare in mkdocs.yml.

Deployment to GitHub pages¶

Automatic deployment to GitHub pages is set up using GitHub actions and workflows. See source code under the .github folder.