📔 SPM Documentation 👋

This repository contains the documentation of the SPM software. It is built using Material for MkDocs, a theme for the static site generator MkDocs.

All the features of Material for MkDocs are described in its reference documentation. We are sponsoring the project and therefore have access to all of the Insiders features.

⚠️ This repository contains all the files used to generate the SPM documentation. This is therefore the place to make some edits and modifications to the documentation. If you only want to read the documentation, please have a look here.

⛷️ Getting started

📑 File layout

MkDocs is configured using the mkdocs.yml file at the root of the Git repository.

The mkdocs.yml file defines the top level navigation for the site. The nav configuration setting in this file defines which pages are included in the global site navigation menu as well as the structure of that menu.

See MkDocs documentation for more details.

🆒 Markdown syntax

MkDocs pages are written using the Markdown syntax.

MkDocs natively supports Markdown extensions that enhance the Markdown writing experience. Plugins, built-in or third-party, are extensions to the MkDocs framework which allow users to add custom functionality and features to their MkDocs projects. These plugins can be used to add additional features such as search or analytics.

See MkDocs documentation for more details, and best-of-mkdocs for a curated list of plugins.

To edit Markdown documents, we recommend Visual Studio Code with its preview mode. If you want to make a quick change, navigate on GitHub to the page of the file you wish to modify (or click on the Edit this page icon) and press the . key: it will open a VS Code environment directly in your browser.

💻 Installation

If you want to edit and build the documentation yourself, you first need to clone or download the repository:

git clone git@github.com:spm/spm-docs.git

Then create a virtual environment for Python and install Material for MkDocs and its dependencies:

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

On Windows, install Python from the Microsoft Store then type the following in a Command Prompt or PowerShell window:

python3 -m venv venv
.\venv\Scripts\activate
pip install --requirement requirements.txt

Still on Windows, if you have issues with the above commands due to restrictions on your system, please run the following after creating the virtual environment:

Powershell.exe -NoProfile -ExecutionPolicy Bypass -File <the full path of the activate.ps1 file>

You can preview the documentation as you work on it thanks to a built-in web server. When you are in the same directory as the mkdocs.yml configuration file, start the server with the command:

mkdocs serve

You can then browse the documentation in your web browser at http://127.0.0.1:8000/. Each time a change is made, the documentation is rebuilt and the page auto-reloaded.

To deploy the documentation, use the following command:

mkdocs build

The documentation is then built as a static site in a directory called site.

The Insiders-only features will be here ignored but available in the public build on the SPM website.

To deactivate the virtual environment when you finished working, use:

deactivate

MkDocs plugins currently used:

• mkdocs-bibtex: a plugin for citation management using bibtex
• MkDocs Video: a plugin to embed videos in the documentation pages

🦁 Style guide

1. Language

Use British English.

2. Code

Format any code included in the documentation as code blocks.

Raw text:

```matlab

code

```

Display text:

code

Format any file names, paths, functions, input variables, etc. as in-line code.

Raw text: `code`

Display text: code

3. Abbreviations

All abbreviations should be defined alphabetically in addons/abbreviations.md in the following format:

*[BOLD]: Blood Oxygen Level Dependent 

To use the abbreviations file on the page you’re creating, add the below at the end of your markdown file:

--8<-- "addons/abbreviations.md"

4. Images

Illustrations should be saved as PNG or SVG files in the docs/assets/figures/ directory. OptiPNG should be applied on PNG files before commit.

To display images with captions, use:

<figure markdown>
  ![Image title](../../../assets/figures/image.png){ width="300" }
  <figcaption>Image caption</figcaption>
</figure>

Videos should be saved as MP4 in the docs/assets/videos/ directory. Videos encoded in other formats can be converted to MP4 with FFmpeg.

5. Information boxes

Additional information can be highlighted using information boxes.

Boxes can be expanded:

!!! tip “Title of your box”
    Text of your box

Or collapsible:

??? tip "Title of your box"
    Text of your box

Use expanded boxes for crucial succinct information. For anything additional or lengthy, use collapsible boxes.

Various icons and colour-coding are available, please use:

• tip for top tips on SPM things
• info for core information not covered in the main text
• note for additional non-essential information
• failure for help on troubleshooting

Full list of icons is available here.

6. Symbols

A selection of symbols can be used. Currently used:

• ++return++ enter/return key
• :material-arrow-right-bold: right facing arrow
• :material-play: play icon

Full list of symbols is available here.

🐛 Testing

🛠️ Build

The documentation is built using GitHub Action after each commit in the main branch with the non-Insiders version of Material for MkDocs.

📝 Spelling

codespell

Detect common misspellings with codespell.

To run codespell interactively on the SPM documentation, use:

codespell -w -i 1 docs

PySpelling

To run PySpelling on the SPM documentation, use:

# Run PySpelling using the default spell checker, Aspell
pyspelling
# Run PySpelling using the Hunspell spell checker
pyspelling --spellchecker hunspell

⛓️ Links Check

markdown-link-check

A GitHub Action checks all Markdown files for broken links (using markdown-link-check).

🧊 Linting

markdownlint

To run markdownlint-cli, a command line interface to markdownlint, use:

markdownlint "docs/**/*.md"

Note that only MkDocs build and codespell will potentially fail during continuous integration on GitHub Actions. The other reports are only advisory, for your perusal.

🥂 Contributing

Contributions are most welcome and appreciated! See the First Contributions project for instructions.

1. GitHub repository: Report issues, make feature requests or open pull requests.
2. SPM@JiscMail: Open mailing list for discussion and questions about SPM.

🎀 License

The SPM Documentation is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, see LICENSE or visit http://creativecommons.org/licenses/by-sa/4.0/.