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.
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.
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.
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 bibtexMkDocs Video
: a plugin to embed videos in the documentation pages
Use British English.
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
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"
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.
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 thingsinfo
for core information not covered in the main textnote
for additional non-essential informationfailure
for help on troubleshooting
Full list of icons is available here.
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.
The documentation is built using GitHub Action after each commit in the main
branch with the non-Insiders version of Material for MkDocs.
Detect common misspellings with codespell
.
To run codespell
interactively on the SPM documentation, use:
codespell -w -i 1 docs
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
A GitHub Action checks all Markdown files for broken links (using markdown-link-check).
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.
Contributions are most welcome and appreciated! See the First Contributions project for instructions.
- GitHub repository: Report issues, make feature requests or open pull requests.
- SPM@JiscMail: Open mailing list for discussion and questions about SPM.
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/.