Writing Documentation

Where possible, we have brought together documentation relating to the Incubator into this one Zensical site, published at https://playbook.rcpch.tech.

Zensical¶

This site is created using Zensical, a drop-in replacement for MkDocs + Material for MkDocs that reads the existing mkdocs.yml configuration. It keeps compatibility with MkDocs/Material configuration and plugins, while moving away from the upstream changes in MkDocs 2.0.

As you’d expect, there is documentation for Zensical, and the reference docs for Material for MkDocs and MkDocs are still useful for authoring features and syntax.

Adding or editing documentation¶

Mostly this just requires creating Markdown files in the docs/ directory of the documentation repository.

Use other pages within this repo to get ideas on the style and the features available such as emoji, icons, admonitions.

Continuous Integration via GitHub Actions¶

Any changes to the live branch of the documentation repository trigger a GitHub Action. This runs Zensical in a temporary application container, builds the site from the Markdown source into a set of static HTML pages, and publishes the site to Azure.

This occurs whether changes are made using online or local, offline editing methods.

Online editing of the Markdown¶

If you are new to Markdown editing, you can use GitHub's interface itself to edit online, by clicking the 'pencil' edit icon in the top right corner of any source code page. There are also external tools like Prose.io and StackEdit which give you a nice interface for editing MarkDown online, and will sync the changes with GitHub for you.

If you need help getting set up, contact us in the Signal chat.

Using a text editor and editing locally¶

More experienced coders can git clone the repo and make changes offline on their local machine before pushing to the remote to either the rcpch organisation's remote, or their own fork. This allows you to run Zensical locally and preview the site as it will appear when pushed to live.

(Mac / Linux) Setting up a development environment¶

Create a virtual environment for the Python modules:

• Use venv (see Venv)
• Use a recent Python 3.x (the Docker image uses Python 3.12)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Start the Zensical server:

zensical serve

Zensical will tell you what URL you can view the site on, which is usually localhost:8000. You can vary this in the settings, if port 8000 is already in use.

(Windows) Setting up a development environment¶

Create a virtual environment with venv. See Venv if you need help setting up.

Then, with GitHub Desktop, clone the repo using the following url

https://github.com/rcpch/rcpch-incubator-playbook.git

cd into the directory (ensuring you are using your virtual environment)

cd rcpch-incubator-playbook

Install the dependencies:

pip install -r requirements.txt

Finally, start the Zensical server with:

zensical serve

Zensical will tell you what URL you can view the site on.

git-committers and mkdocs-with-pdf plugins¶

These plugins can add 10-15 seconds of build time to the site, so when developing locally, they are disabled by default. They are enabled by using environment variables, if you want to test that they work locally before pushing to the remote:

export ENABLE_GIT_COMMITTERS=true; zensical serve
export ENABLE_PDF_EXPORT=true; zensical serve

You should always build the site at least once with both PDF export and Git Committers enabled, to ensure there are no issues, before pushing to the remote.

Notes¶

• On some platforms, if you get the error ModuleNotFoundError: No module named '_ctypes', then you need to run sudo apt-get install libffi-dev, or the equivalent on your platform. Then, recompile your Python (if using pyenv, simply pyenv install 3.10.2 will recompile that Python binary).

• Tested Oct 2022 on Linux Mint 21.0

Adding a new page¶

• Create a new Markdown file in a subfolder in the docs folder. Use a similar existing page as a starting point, then adjust the content and front matter.

Because of the way we have set up the left sidebar navigation, new pages are not automatically added to the navigation.

(This allows us to have pages which are work-in-progress, available on the live site for review, but not in the navigation, hence only those who have the link would easily find it)

See the next section for how to add pages to the navigation.

Adding navigation for the page¶

Add navigation by editing the nav: tree element in mkdocs.yml. Below is an excerpt from the nav: in this project. You can see how the top level Navbar headings Home and About are defined, and how the sidebar headings work. You can nest several levels deep, if needed.

nav:
  - Home: "index.md"
  - About:
      - "about/about.md"

By manually specifying the navigation in this way, we have control over the precise appearance of subfolder names (which are otherwise rendered in Title Case, but this doesn't work for acronyms). Also, we can customise the order of listing of sidebar headings, which would otherwise be ordered alphabetically.

Page title in the navigation¶

The page title that will be displayed in the left sidebar navigation is set in the YAML front matter:

---
title: Some Page Title
reviewers:
---

Heading on the page¶

The heading that will be displayed on the page is set using the first <h1> heading (i.e. one hashtag #)

# Heading, which can be different to the sidebar title

Reviewers¶

Reviewers are encouraged to add their details to the reviewers: section of the YAML front matter. This enables us to evidence that each page has been reviewed by multiple members of the team.

---
title: Some Page Title
reviewers: Dr Anchit Chandran, ...
---

Publishing is automated¶

When you push new changes to ANY branch of this repo, or it you open a Pull Request, Azure will automatically build a version of the site for review. You need to visit the Azure portal to see the URL of the deployment, as it depends on the branch name.

Therefore, you don't need to run zensical build or any deploy commands manually or locally - it’s done for you if you push to branches or PRs on GitHub.

Plugins¶

Zensical supports MkDocs plugins and features through compatibility modules. We already use a small set to extend the capabilities of MarkDown, making the documentation look nicer and function better.