UCL-ARC · paddyroddy · Oct 22, 2024 · Oct 22, 2024 · Oct 22, 2024 · Oct 22, 2024
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
@@ -0,0 +1,2 @@
+---
+MD013: false
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -9,6 +9,12 @@ repos:
       - id: ruff-format
         args:
           - --config=pyproject.toml
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.42.0
+    hooks:
+      - id: markdownlint-fix
+        args:
+          - --dot
   - repo: https://github.com/Lucas-C/pre-commit-hooks
     rev: v1.5.5
     hooks:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,3 +1,5 @@
+# Contributing Guide
+
 This template and our [recommendation pages][website] were made by [research
 software engineers] at [UCL's Centre for Advanced Research Computing][UCL ARC].
 We made it with research software projects in mind, but whoever you are, we hope

diff --git a/README.md b/README.md
@@ -1,7 +1,9 @@
+<!-- markdownlint-disable MD033 MD041 -->
 <div style="text-align: center;" align="center">
   <img src="https://raw.githubusercontent.com/UCL-ARC/python-tooling/main/images/logo.svg" alt="UCL ARC Python tooling logo" width="120"/>
   <h1> UCL ARC Python Recommendations</h1>
 </div>
+<!-- markdownlint-restore -->
 
 This repository collects the [UCL ARC] recommendations for a research software
 project in Python. It contains a template for new Python packages and a
@@ -73,80 +75,86 @@ We also have a detailed [tutorial](tutorial.md) that has been given in a couple
 The tutorial goes into much more pedagogical detail, it both describes using the template to create a package
 and how to use the newly created package with some of the tools included.
 
-1.  Install [cookiecutter] in a Conda or `venv` environment (commented lines for
-    Conda example).
-
-    ```
-    # conda create --channel conda-forge --name new-env-name
-    # conda activate new-env-name
-    # conda install pip
-    pip install cookiecutter
-    ```
-
-2.  Run cookiecutter in the desired directory
-    ```
-    cookiecutter gh:ucl-arc/python-tooling
-    ```
-    If you have this repo locally (this may be the case if you are developing),
-    you can run the following:
-    ```
-    cookiecutter /path/to/your/checkout/of/python-tooling
-    ```
-3.  A series of questions will pop up to configure the project. Type the answer
-    or hit return to use the default option (shown in parenthesis).
-
-    Note that these project variables are defined in the `cookiecutter.json`
-    file.
-
-4.  This will create a specific directory structure.
-
-    For example, for a project with the following variables:
-
-    ```
-    project_name [Python Template]: PROJECT_NAME
-    project_slug [python-template]: PROJECT_SLUG
-    package_name [python_template]: PACKAGE_NAME
-    ```
-
-    we will get a project folder named `PROJECT_SLUG`, structured like this:
-
-    ```
-    PROJECT_SLUG
-    ├── ...
-    ├── README.md
-    ├── pyproject.toml
-    ├── src
-    │   └── PACKAGE_NAME
-    │       └── __init__.py
-    └── tests
-        └── test_dummy.py
-    ```
-
-    And the `PROJECT_NAME` will appear in the README.md as the human-readable
-    name of the project.
-
-    ```
-    cat PROJECT_SLUG/README.md
-    # PROJECT_NAME
-    ...
-    ```
-
-5.  To work on your project, initialise a Git repository and _install_ it in
-    editable mode.
-    ```
-    cd PROJECT_SLUG
-    git init
-    python -m pip install -e ".[dev]"
-    ```
-6.  Build your package
-    ```
-    python -m build
-    ```
+1. Install [cookiecutter] in a Conda or `venv` environment (commented lines for
+   Conda example).
+
+   ```sh
+   # conda create --channel conda-forge --name new-env-name
+   # conda activate new-env-name
+   # conda install pip
+   pip install cookiecutter
+   ```
+
+2. Run cookiecutter in the desired directory
+
+   ```sh
+   cookiecutter gh:ucl-arc/python-tooling
+   ```
+
+   If you have this repo locally (this may be the case if you are developing),
+   you can run the following:
+
+   ```sh
+   cookiecutter /path/to/your/checkout/of/python-tooling
+   ```
+
+3. A series of questions will pop up to configure the project. Type the answer
+   or hit return to use the default option (shown in parenthesis).
+
+   Note that these project variables are defined in the `cookiecutter.json`
+   file.
+
+4. This will create a specific directory structure.
+
+   For example, for a project with the following variables:
+
+   ```yaml
+   project_name [Python Template]: PROJECT_NAME
+   project_slug [python-template]: PROJECT_SLUG
+   package_name [python_template]: PACKAGE_NAME
+   ```
+
+   we will get a project folder named `PROJECT_SLUG`, structured like this:
+
+   ```sh
+   PROJECT_SLUG
+   ├── ...
+   ├── README.md
+   ├── pyproject.toml
+   ├── src
+   │   └── PACKAGE_NAME
+   │       └── __init__.py
+   └── tests
+       └── test_dummy.py
+   ```
+
+   And the `PROJECT_NAME` will appear in the README.md as the human-readable
+   name of the project.
+
+   ```sh
+   cat PROJECT_SLUG/README.md
+   # PROJECT_NAME
+   ...
+   ```
+
+5. To work on your project, initialise a Git repository and _install_ it in
+   editable mode.
+
+   ```sh
+   cd PROJECT_SLUG
+   git init
+   python -m pip install -e ".[dev]"
+   ```
+
+6. Build your package
+
+   ```sh
+   python -m build
+   ```
 
 ## Notes for developers
 
-<details>
-<summary>Click to expand...</summary>
+<details><summary>Click to expand...</summary> <!-- markdownlint-disable-line MD033 -->
 
 First, clone repository
 
@@ -157,7 +165,7 @@ First, clone repository
 - Clone the repository by typing (or copying) the following line in a terminal
   at your selected path in your machine:
 
-```
+```sh
 git clone git@github.com:UCL-ARC/python-tooling.git
 cd python-tooling
 ```
@@ -166,7 +174,7 @@ cd python-tooling
 
 - To create and remove your virtual environment
 
-  ```
+  ```sh
   conda create -n ptoolingVE pip -c conda-forge
   conda activate ptoolingVE
   conda deactivate ptoolingVE
@@ -176,7 +184,7 @@ cd python-tooling
 - To run template in the same path of this repo. We do a test cookiecut of a
   dummy package and install it to ensure the template setup works.
 
-  ```
+  ```sh
   cookiecutter .
   cd python-template
   git init
@@ -185,13 +193,13 @@ cd python-tooling
 
 - To run cookiecutter using a specific branch of the template:
 
-  ```
+  ```sh
   cookiecutter https://github.com/UCL-ARC/python-tooling --checkout <branch-name>
   ```
 
 - To run the tests locally:
 
-  ```
+  ```sh
   pytest -s
   ```
 
@@ -203,13 +211,13 @@ sub-directory, and are written in markdown.
 
 To build the webpage locally (for testing)
 
-1.  [Install jekyll](https://jekyllrb.com/docs/installation)
-2.  Run `bundle install` from the `docs/` directory of this repository to
-    install dependencies.
-3.  Run `bundle exec jekyll serve` from the root directory of this repository.
-    This should fire up a local web server and tell you its address. By default
-    the server will automatically refresh the HTML pages if any changes are made
-    to the markdown sources.
+1. [Install jekyll](https://jekyllrb.com/docs/installation)
+2. Run `bundle install` from the `docs/` directory of this repository to
+   install dependencies.
+3. Run `bundle exec jekyll serve` from the root directory of this repository.
+   This should fire up a local web server and tell you its address. By default
+   the server will automatically refresh the HTML pages if any changes are made
+   to the markdown sources.
 
 See the [jekyll docs](https://jekyllrb.com/docs) for more info.
 

diff --git a/docs/pages/benchmarking-profiling.md b/docs/pages/benchmarking-profiling.md
@@ -3,29 +3,29 @@ title: Benchmarking and profiling
 layout: default
 ---
 
-# Benchmarking
+## Benchmarking
 
 | Name                                         | Short description                                                                                                                                                                                                                                                                                                                                                                         | 🚦  |
 | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
 | [asv](https://asv.readthedocs.io/en/stable/) | A tool for benchmarking Python packages over their lifetime. Allows you to write benchmarks and then run them against every commit in the repository, to identify where performance increased or decreased. Comparative benchmarks can also be run, which can be useful for [running them in CI using GitHub runners](https://labs.quansight.org/blog/2021/08/github-actions-benchmarks). | 🟢  |
 
-# Profiling
+## Profiling
 
-## Time
+### Time
 
 | Name                                                          | Short description                                                                                                                              | 🚦  |
 | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
 | [pyinstrument](https://pyinstrument.readthedocs.io/en/stable) | Python profiler. Tells you how long individual lines of code take to run, so you can focus on the slowest part of your program to speed it up. | 🟢  |
 | [line_profiler](https://pypi.org/project/line-profiler/)      | A tool for line-by-line profiling of functions.                                                                                                | 🟠  |
 
-## Memory
+### Memory
 
 | Name                                                         | Short description                                                                                                                                                                                                                           | 🚦  |
 | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
 | [memray](https://bloomberg.github.io/memray/)                | Tracks and reports memory allocations, both in Python code and in compiled extension modules. It also has a [plugin](https://pytest-memray.readthedocs.io/en/latest/) for easy integration with pytest. Only works on Linux and macOS.      | 🟠  |
 | [memory_profiler](https://pypi.org/project/memory-profiler/) | No longer actively maintained. A Python module for monitoring memory consumption of a process alongside line-by-line analysis of memory consumption. Might be a useful alternative to memray if you need to do memory profiling on Windows. | 🟠  |
 
-## General/other tools
+### General/other tools
 
 | Name                                               | Short description                                                                                 | 🚦  |
 | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- | :-: |

diff --git a/docs/pages/ci.md b/docs/pages/ci.md
@@ -3,7 +3,7 @@ title: Continuous integration
 layout: default
 ---
 
-# Continuous integration (CI)
+## Continuous integration (CI)
 
 | Name                                                                                  | Short description                                                                                                                                   | 🚦  |
 | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
@@ -13,12 +13,11 @@ layout: default
 | [Travis CI](https://docs.travis-ci.com/)                                              | Continuous integration and continuous delivery platform.                                                                                            | 🟠  |
 | [pre-commit.ci](https://pre-commit.ci/)                                               | A bot that adds a pre-commit job to your GitHub Actions CI, and can automatically fix most trivial linting failures. Free for open-source projects. | 🟢  |
 
-<details>
-<summary> 🟢 explanation</summary>
+<details><summary> 🟢 explanation</summary><!-- markdownlint-disable-line MD033 -->
 We have many projects using GitHub CI and, it has good integration with GitHub itself, and is free for public repositories (with limited free monthly minutes for private repositories).
 </details>
 
-# Coverage monitoring
+## Coverage monitoring
 
 These services report and track test code coverage over time. They render the
 code with highlighting to show which lines are not executed by tests. See
@@ -30,7 +29,6 @@ during tests.
 | [Codecov](https://docs.codecov.com/docs) | Hosted service to report code coverage metrics. Occasionally slow to update after a report is updated, can be configured to add extra CI checks. This service is probably more widely used and is [free for both open-source and private projects](https://about.codecov.io/pricing/). | 🟢  |
 | [Coveralls](https://docs.coveralls.io/)  | Hosted service to report code coverage metrics. Very similar to codecov and we don't strongly recommend one over the other. This service is only [free for open-source projects](https://coveralls.io/pricing).                                                                        | 🟢  |
 
-<details>
-<summary> 🟢 explanation</summary>
+<details><summary> 🟢 explanation</summary> <!-- markdownlint-disable-line MD033 -->
 Both services are similar, so both 🟢.
 </details>
diff --git a/docs/pages/community.md b/docs/pages/community.md
@@ -3,7 +3,7 @@ title: Community
 layout: default
 ---
 
-# Community building
+## Community building
 
 There are many platforms to build a community for users and developers. We
 recommend you choose one, and not more than one. If you are creating a new

diff --git a/docs/pages/docs.md b/docs/pages/docs.md
@@ -3,7 +3,7 @@ title: Documentation
 layout: default
 ---
 
-# Documentation
+## Documentation
 
 With Python, as with many other languages, it's very common to automatically
 create a web page with documentation. This can include reference for the API
@@ -23,7 +23,7 @@ If you're using GitHub, one option is to host your docs on [GitHub pages].
 [our template]: https://github.com/UCL-ARC/python-tooling?tab=readme-ov-file#using-this-template
 [template-docs-dot-yaml]: https://github.com/UCL-ARC/python-tooling/blob/main/%7B%7Bcookiecutter.project_slug%7D%7D/.github/workflows/docs.yml
 
-## Documentation build tools
+### Documentation build tools
 
 | Name      | Short description                                                                                                                                               | 🚦  |
 | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
@@ -32,8 +32,7 @@ If you're using GitHub, one option is to host your docs on [GitHub pages].
 | [gitbook] | General documentation builder; integrates with GitHub.                                                                                                          | 🟠  |
 | [pdoc]    | Auto-generates API documentation from docstrings, beginner friendly but with less of a plugin ecosystem than others.                                            | 🟠  |
 
-<details markdown="block">
-<summary>More details about Sphinx</summary>
+<details markdown="block"><summary>More details about Sphinx</summary><!-- markdownlint-disable-line MD033 -->
 
 We marginally recommend [MkDocs] over [Sphinx] due to it's ease of use,
 preference for Markdown, and more support for a variety of docstring styles.
@@ -44,7 +43,7 @@ a [Sphinx extension](#sphinx-extensions) that does not have an equivalent
 [MkDocs plugin](https://github.com/mkdocs/catalog), or if you are part of a
 community that heavily uses [Sphinx] then we recommend you use that instead.
 
-### See also
+#### See also
 
 - Our internal discussions about which to recommend
   ([#16](https://github.com/UCL-ARC/python-tooling/issues/16) and
@@ -60,13 +59,13 @@ community that heavily uses [Sphinx] then we recommend you use that instead.
 [gitbook]: https://www.gitbook.com/
 [pdoc]: https://pdoc.dev/
 
-## MkDocs plugins
+### MkDocs plugins
 
 | Name                                                          | Short description                            | 🚦  |
 | ------------------------------------------------------------- | -------------------------------------------- | :-: |
 | [mkdocstrings-python](https://mkdocstrings.github.io/python/) | Automatically generates API reference pages. | 🟢  |
 
-## Sphinx extensions
+### Sphinx extensions
 
 | Name                                                                 | Short description                                                | 🚦  |
 | -------------------------------------------------------------------- | ---------------------------------------------------------------- | :-: |