Contributing to HEMMS Documentation¶

This guide covers how to add and edit pages in the HEMMS documentation site, which is built with MkDocs Material.

Prerequisites¶

Install the documentation toolchain:

make docs-install

This installs MkDocs Material and all required plugins into your current Python environment. If you prefer isolation, use a virtual environment:

python3 -m venv .venv-docs
source .venv-docs/bin/activate
make docs-install

Local preview¶

Start a live-reloading dev server:

make docs-serve

Open http://localhost:8000 in your browser. Edits to any .md file or mkdocs.yml trigger an automatic rebuild and browser refresh.

Adding a new page¶

Create a Markdown file in the appropriate docs/ subfolder:
```
touch docs/modules/criticality/faq.md
```

Add YAML frontmatter at the top:

---
title: Criticality FAQ
description: Frequently asked questions about the criticality module
---

Write your content using standard Markdown.

Register the page in mkdocs.yml under the nav: section:

nav:
  - Modules:
    - Equipment Criticality:
      - modules/criticality/index.md
      - FAQ: modules/criticality/faq.md   # <-- add here

Check the result at http://localhost:8000.

Writing conventions¶

Headings¶

Use # for the page title (one per page), ## for major sections, and ### for subsections. MkDocs generates the table of contents from headings.

Admonitions¶

Use admonitions to highlight important information:

!!! info "Good to know"
    This is an informational callout.

!!! warning
    This warns the reader about a potential issue.

!!! tip "Pro tip"
    A helpful suggestion for advanced users.

!!! danger "Breaking change"
    Something that could cause data loss or downtime.

Available types: note, abstract, info, tip, success, question, warning, failure, danger, bug, example, quote.

Collapsible admonitions use ??? instead of !!!:

??? example "Click to expand"
    Hidden content revealed on click.

Code blocks¶

Specify the language for syntax highlighting:

```python
class MyModel(models.Model):
    _name = 'my.model'
    name = fields.Char(string='Name', required=True)
```

Add a title to code blocks:

```python title="models/my_model.py"
class MyModel(models.Model):
    _name = 'my.model'
```

Highlight specific lines:

```python hl_lines="2 3"
class MyModel(models.Model):
    _name = 'my.model'
    name = fields.Char(string='Name')
```

Screenshots and images¶

Place images in the docs/assets/ folder and reference them with relative paths:

![Equipment form with criticality badge](../assets/equipment-form-criticality.png)

Always include descriptive alt text. Images are displayed with the glightbox plugin — clicking on an image opens a lightbox overlay.

Cross-linking between pages¶

Use relative paths from the current file:

See the [Equipment Criticality module](../modules/criticality/index.md) for details.

Link to a specific section using the heading anchor:

See [SLA Configuration](../modules/workflow/configuration.md#sla-settings).

Tabs¶

Use content tabs for platform-specific instructions:

=== "Private Hospital"

    ```bash
    make up-private
    make install-private
    ```

=== "Government Hospital"

    ```bash
    make up-gov
    make install-gov
    ```

Definition lists¶

Use for glossary-style entries:

BME
:   Biomedical Engineering — the department responsible for medical equipment.

SLA
:   Service Level Agreement — the maximum time allowed for each repair stage.

Building for production¶

To verify the site builds without warnings:

make docs-build

This runs mkdocs build --strict, which fails on any broken links or configuration warnings. The output goes to the site/ directory (git-ignored).

Submitting changes¶

Create a feature branch:
```
git checkout -b docs/my-topic
```
Make your changes and verify locally with make docs-serve.
Run the strict build to catch issues:
```
make docs-build
```

Commit and push:

git add docs/ mkdocs.yml
git commit -m "docs: add my-topic documentation"
git push -u origin docs/my-topic

Open a pull request. The CI workflow will build the docs and report any errors.