Skip to content

Commit fc750bc

Browse files
paddyroddypaddyroddy
committed
Add markdownlint and tidy up markdown 
1 parent a867d7b commit fc750bc

23 files changed

+209
-174
lines changed

‎.markdownlint.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
---
2+
MD013: false

‎.pre-commit-config.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,12 @@ repos:
99
- id: ruff-format
1010
args:
1111
- --config=pyproject.toml
12+
- repo: https://github.com/igorshubovych/markdownlint-cli
13+
rev: v0.42.0
14+
hooks:
15+
- id: markdownlint-fix
16+
args:
17+
- --dot
1218
- repo: https://github.com/Lucas-C/pre-commit-hooks
1319
rev: v1.5.5
1420
hooks:

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Contributing Guide
2+
13
This template and our [recommendation pages][website] were made by [research
24
software engineers] at [UCL's Centre for Advanced Research Computing][UCL ARC].
35
We made it with research software projects in mind, but whoever you are, we hope

‎README.md‎

Lines changed: 91 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
1+
<!-- markdownlint-disable MD033 MD041 -->
12
<div style="text-align: center;" align="center">
23
<img src="https://raw.githubusercontent.com/UCL-ARC/python-tooling/main/images/logo.svg" alt="UCL ARC Python tooling logo" width="120"/>
34
<h1> UCL ARC Python Recommendations</h1>
45
</div>
6+
<!-- markdownlint-restore -->
57

68
This repository collects the [UCL ARC] recommendations for a research software
79
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
7375
The tutorial goes into much more pedagogical detail, it both describes using the template to create a package
7476
and how to use the newly created package with some of the tools included.
7577

76-
1. Install [cookiecutter] in a Conda or `venv` environment (commented lines for
77-
Conda example).
78-
79-
```
80-
# conda create --channel conda-forge --name new-env-name
81-
# conda activate new-env-name
82-
# conda install pip
83-
pip install cookiecutter
84-
```
85-
86-
2. Run cookiecutter in the desired directory
87-
```
88-
cookiecutter gh:ucl-arc/python-tooling
89-
```
90-
If you have this repo locally (this may be the case if you are developing),
91-
you can run the following:
92-
```
93-
cookiecutter /path/to/your/checkout/of/python-tooling
94-
```
95-
3. A series of questions will pop up to configure the project. Type the answer
96-
or hit return to use the default option (shown in parenthesis).
97-
98-
Note that these project variables are defined in the `cookiecutter.json`
99-
file.
100-
101-
4. This will create a specific directory structure.
102-
103-
For example, for a project with the following variables:
104-
105-
```
106-
project_name [Python Template]: PROJECT_NAME
107-
project_slug [python-template]: PROJECT_SLUG
108-
package_name [python_template]: PACKAGE_NAME
109-
```
110-
111-
we will get a project folder named `PROJECT_SLUG`, structured like this:
112-
113-
```
114-
PROJECT_SLUG
115-
├── ...
116-
├── README.md
117-
├── pyproject.toml
118-
├── src
119-
│ └── PACKAGE_NAME
120-
│ └── __init__.py
121-
└── tests
122-
└── test_dummy.py
123-
```
124-
125-
And the `PROJECT_NAME` will appear in the README.md as the human-readable
126-
name of the project.
127-
128-
```
129-
cat PROJECT_SLUG/README.md
130-
# PROJECT_NAME
131-
...
132-
```
133-
134-
5. To work on your project, initialise a Git repository and _install_ it in
135-
editable mode.
136-
```
137-
cd PROJECT_SLUG
138-
git init
139-
python -m pip install -e ".[dev]"
140-
```
141-
6. Build your package
142-
```
143-
python -m build
144-
```
78+
1. Install [cookiecutter] in a Conda or `venv` environment (commented lines for
79+
Conda example).
80+
81+
```sh
82+
# conda create --channel conda-forge --name new-env-name
83+
# conda activate new-env-name
84+
# conda install pip
85+
pip install cookiecutter
86+
```
87+
88+
2. Run cookiecutter in the desired directory
89+
90+
```sh
91+
cookiecutter gh:ucl-arc/python-tooling
92+
```
93+
94+
If you have this repo locally (this may be the case if you are developing),
95+
you can run the following:
96+
97+
```sh
98+
cookiecutter /path/to/your/checkout/of/python-tooling
99+
```
100+
101+
3. A series of questions will pop up to configure the project. Type the answer
102+
or hit return to use the default option (shown in parenthesis).
103+
104+
Note that these project variables are defined in the `cookiecutter.json`
105+
file.
106+
107+
4. This will create a specific directory structure.
108+
109+
For example, for a project with the following variables:
110+
111+
```yaml
112+
project_name [Python Template]: PROJECT_NAME
113+
project_slug [python-template]: PROJECT_SLUG
114+
package_name [python_template]: PACKAGE_NAME
115+
```
116+
117+
we will get a project folder named `PROJECT_SLUG`, structured like this:
118+
119+
```sh
120+
PROJECT_SLUG
121+
├── ...
122+
├── README.md
123+
├── pyproject.toml
124+
├── src
125+
│ └── PACKAGE_NAME
126+
│ └── __init__.py
127+
└── tests
128+
└── test_dummy.py
129+
```
130+
131+
And the `PROJECT_NAME` will appear in the README.md as the human-readable
132+
name of the project.
133+
134+
```sh
135+
cat PROJECT_SLUG/README.md
136+
# PROJECT_NAME
137+
...
138+
```
139+
140+
5. To work on your project, initialise a Git repository and _install_ it in
141+
editable mode.
142+
143+
```sh
144+
cd PROJECT_SLUG
145+
git init
146+
python -m pip install -e ".[dev]"
147+
```
148+
149+
6. Build your package
150+
151+
```sh
152+
python -m build
153+
```
145154

146155
## Notes for developers
147156

148-
<details>
149-
<summary>Click to expand...</summary>
157+
<details><summary>Click to expand...</summary> <!-- markdownlint-disable-line MD033 -->
150158

151159
First, clone repository
152160

@@ -157,7 +165,7 @@ First, clone repository
157165
- Clone the repository by typing (or copying) the following line in a terminal
158166
at your selected path in your machine:
159167

160-
```
168+
```sh
161169
git clone git@github.com:UCL-ARC/python-tooling.git
162170
cd python-tooling
163171
```
@@ -166,7 +174,7 @@ cd python-tooling
166174

167175
- To create and remove your virtual environment
168176

169-
```
177+
```sh
170178
conda create -n ptoolingVE pip -c conda-forge
171179
conda activate ptoolingVE
172180
conda deactivate ptoolingVE
@@ -176,7 +184,7 @@ cd python-tooling
176184
- To run template in the same path of this repo. We do a test cookiecut of a
177185
dummy package and install it to ensure the template setup works.
178186

179-
```
187+
```sh
180188
cookiecutter .
181189
cd python-template
182190
git init
@@ -185,13 +193,13 @@ cd python-tooling
185193

186194
- To run cookiecutter using a specific branch of the template:
187195

188-
```
196+
```sh
189197
cookiecutter https://github.com/UCL-ARC/python-tooling --checkout <branch-name>
190198
```
191199

192200
- To run the tests locally:
193201

194-
```
202+
```sh
195203
pytest -s
196204
```
197205

@@ -203,13 +211,13 @@ sub-directory, and are written in markdown.
203211

204212
To build the webpage locally (for testing)
205213

206-
1. [Install jekyll](https://jekyllrb.com/docs/installation)
207-
2. Run `bundle install` from the `docs/` directory of this repository to
208-
install dependencies.
209-
3. Run `bundle exec jekyll serve` from the root directory of this repository.
210-
This should fire up a local web server and tell you its address. By default
211-
the server will automatically refresh the HTML pages if any changes are made
212-
to the markdown sources.
214+
1. [Install jekyll](https://jekyllrb.com/docs/installation)
215+
2. Run `bundle install` from the `docs/` directory of this repository to
216+
install dependencies.
217+
3. Run `bundle exec jekyll serve` from the root directory of this repository.
218+
This should fire up a local web server and tell you its address. By default
219+
the server will automatically refresh the HTML pages if any changes are made
220+
to the markdown sources.
213221

214222
See the [jekyll docs](https://jekyllrb.com/docs) for more info.
215223

‎docs/pages/benchmarking-profiling.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,29 +3,29 @@ title: Benchmarking and profiling
33
layout: default
44
---
55

6-
# Benchmarking
6+
## Benchmarking
77

88
| Name | Short description | 🚦 |
99
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
1010
| [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). | 🟢 |
1111

12-
# Profiling
12+
## Profiling
1313

14-
## Time
14+
### Time
1515

1616
| Name | Short description | 🚦 |
1717
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
1818
| [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. | 🟢 |
1919
| [line_profiler](https://pypi.org/project/line-profiler/) | A tool for line-by-line profiling of functions. | 🟠 |
2020

21-
## Memory
21+
### Memory
2222

2323
| Name | Short description | 🚦 |
2424
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
2525
| [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. | 🟠 |
2626
| [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. | 🟠 |
2727

28-
## General/other tools
28+
### General/other tools
2929

3030
| Name | Short description | 🚦 |
3131
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------- | :-: |

‎docs/pages/ci.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Continuous integration
33
layout: default
44
---
55

6-
# Continuous integration (CI)
6+
## Continuous integration (CI)
77

88
| Name | Short description | 🚦 |
99
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
@@ -13,12 +13,11 @@ layout: default
1313
| [Travis CI](https://docs.travis-ci.com/) | Continuous integration and continuous delivery platform. | 🟠 |
1414
| [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. | 🟢 |
1515

16-
<details>
17-
<summary> 🟢 explanation</summary>
16+
<details><summary> 🟢 explanation</summary><!-- markdownlint-disable-line MD033 -->
1817
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).
1918
</details>
2019

21-
# Coverage monitoring
20+
## Coverage monitoring
2221

2322
These services report and track test code coverage over time. They render the
2423
code with highlighting to show which lines are not executed by tests. See
@@ -30,7 +29,6 @@ during tests.
3029
| [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/). | 🟢 |
3130
| [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). | 🟢 |
3231

33-
<details>
34-
<summary> 🟢 explanation</summary>
32+
<details><summary> 🟢 explanation</summary> <!-- markdownlint-disable-line MD033 -->
3533
Both services are similar, so both 🟢.
3634
</details>

‎docs/pages/community.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Community
33
layout: default
44
---
55

6-
# Community building
6+
## Community building
77

88
There are many platforms to build a community for users and developers. We
99
recommend you choose one, and not more than one. If you are creating a new

‎docs/pages/docs.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Documentation
33
layout: default
44
---
55

6-
# Documentation
6+
## Documentation
77

88
With Python, as with many other languages, it's very common to automatically
99
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].
2323
[our template]: https://github.com/UCL-ARC/python-tooling?tab=readme-ov-file#using-this-template
2424
[template-docs-dot-yaml]: https://github.com/UCL-ARC/python-tooling/blob/main/%7B%7Bcookiecutter.project_slug%7D%7D/.github/workflows/docs.yml
2525

26-
## Documentation build tools
26+
### Documentation build tools
2727

2828
| Name | Short description | 🚦 |
2929
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
@@ -32,8 +32,7 @@ If you're using GitHub, one option is to host your docs on [GitHub pages].
3232
| [gitbook] | General documentation builder; integrates with GitHub. | 🟠 |
3333
| [pdoc] | Auto-generates API documentation from docstrings, beginner friendly but with less of a plugin ecosystem than others. | 🟠 |
3434

35-
<details markdown="block">
36-
<summary>More details about Sphinx</summary>
35+
<details markdown="block"><summary>More details about Sphinx</summary><!-- markdownlint-disable-line MD033 -->
3736

3837
We marginally recommend [MkDocs] over [Sphinx] due to it's ease of use,
3938
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
4443
[MkDocs plugin](https://github.com/mkdocs/catalog), or if you are part of a
4544
community that heavily uses [Sphinx] then we recommend you use that instead.
4645

47-
### See also
46+
#### See also
4847

4948
- Our internal discussions about which to recommend
5049
([#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.
6059
[gitbook]: https://www.gitbook.com/
6160
[pdoc]: https://pdoc.dev/
6261

63-
## MkDocs plugins
62+
### MkDocs plugins
6463

6564
| Name | Short description | 🚦 |
6665
| ------------------------------------------------------------- | -------------------------------------------- | :-: |
6766
| [mkdocstrings-python](https://mkdocstrings.github.io/python/) | Automatically generates API reference pages. | 🟢 |
6867

69-
## Sphinx extensions
68+
### Sphinx extensions
7069

7170
| Name | Short description | 🚦 |
7271
| -------------------------------------------------------------------- | ---------------------------------------------------------------- | :-: |

0 commit comments

Comments
 (0)