Add markdown link checker & update broken links (#527)

.github/workflows/commit-ci.yml

@@ -11,7 +11,9 @@ on:
       - CITATION
       - AUTHORS
       - doc/**
+      - docs/**
       - .readthedocs.yml
+      - .pre-commit-config.yaml
 
 defaults:
   run:

.github/workflows/link-check.yml

@@ -0,0 +1,18 @@
+name: Markdown link check
+
+on:
+  schedule:  # runs every monday at 9 am
+    - cron: "0 9 * * 1"
+  pull_request:
+    branches:
+      - "main"
+    paths:
+      - "**.md"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: markdown-link-check
+        uses: gaurav-nelson/github-action-markdown-link-check@1.0.15

.github/workflows/pr-ci.yml

@@ -11,7 +11,9 @@ on:
       - CITATION
       - AUTHORS
       - doc/**
+      - docs/**
       - .readthedocs.yml
+      - .pre-commit-config.yaml
 
 defaults:
   run:

CONTRIBUTING.md

@@ -7,7 +7,7 @@ Some of the resources to look at if you're interested in contributing:
 * [Join us on Gitter to chat!](https://app.gitter.im/#/room/#calliope-project_calliope:gitter.im)
 * Look at our [milestones](https://github.com/calliope-project/calliope/milestones) and [projects](https://github.com/calliope-project/calliope/projects) on GitHub for an idea on where development is headed
 * Look at [open issues tagged with "help wanted"](https://github.com/calliope-project/calliope/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) and ["good first issue"](https://github.com/calliope-project/calliope/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-* Look at the [development guide in our documentation](http://calliope.readthedocs.io/en/latest/user/develop.html)
+* Look at the [development guide in our documentation](http://calliope.readthedocs.io/en/stable/user/develop.html)
 
 ## Licensing
 
@@ -27,18 +27,18 @@ If reporting an error when running Calliope interactively in a Python session, p
 
 ## Submitting changes
 
-Look at the [development guide in our documentation](http://calliope.readthedocs.io/en/latest/user/develop.html) for information on how to get set up for development.
+Look at the [development guide in our documentation](http://calliope.readthedocs.io/en/stable/user/develop.html) for information on how to get set up for development.
 
 To contribute changes:
 
 1. Fork the project on GitHub
 2. Create a feature branch to work on in your fork (``git checkout -b new-fix-or-feature``)
 3. Add your name to the ``AUTHORS`` file
-4. Commit your changes to the feature branch after running black to format your code (formatting is automatic if the ``pre-commit`` hooks have been installed; see [below](#codeconvention) for more info)
+4. Commit your changes to the feature branch after running black to format your code (formatting is automatic if the ``pre-commit`` hooks have been installed; see [below](#coding-conventions) for more info)
 5. Push the branch to GitHub (``git push origin new-fix-or-feature``)
 6. On GitHub, create a new [pull request](https://github.com/calliope-project/calliope/pull/new/main) from the feature branch
 
-Our [development guide](http://calliope.readthedocs.io/en/latest/user/develop.html) gives a more detailed description of each step, if you're new to working with GitHub.
+Our [development guide](http://calliope.readthedocs.io/en/stable/user/develop.html) gives a more detailed description of each step, if you're new to working with GitHub.
 
 ### Pull requests
 
@@ -67,13 +67,13 @@ All tests are in the ``tests`` directory and use [pytest](https://docs.pytest.or
 
 Our test coverage is not perfect and an easy way to contribute code is to work on better tests.
 
-## <a name="codeconvention"></a>Coding conventions
+## Coding conventions
 
 Start reading our code and you'll get the hang of it.
 
 We mostly follow the official [Style Guide for Python Code (PEP8)](https://www.python.org/dev/peps/pep-0008/).
 
-We have chosen to use the uncompromising code formatter, [`black`](https://github.com/psf/black/).  If run from the root directory of this repo, `pyproject.toml` should ensure the line lengths are restricted to 88.  The philosophy behind using black is to have uniform style throughout the project dictated by code.  Since `black` is designed to minimise diffs, and make patches more human readable, this also makes code reviews more efficient.  To make this a smooth experience, you should add a black formatting script to your git pre-commit hooks before creating a PR.  We provide a quick and easy way to set this up as part of the [development guide in our documentation](http://calliope.readthedocs.io/en/latest/user/develop.html#installing-a-development-version).
+We have chosen to use the uncompromising code formatter, [`black`](https://github.com/psf/black/).  If run from the root directory of this repo, `pyproject.toml` should ensure the line lengths are restricted to 88.  The philosophy behind using black is to have uniform style throughout the project dictated by code.  Since `black` is designed to minimise diffs, and make patches more human readable, this also makes code reviews more efficient.  To make this a smooth experience, you should add a black formatting script to your git pre-commit hooks before creating a PR.  We provide a quick and easy way to set this up as part of the [development guide in our documentation](http://calliope.readthedocs.io/en/stable/user/develop.html#installing-a-development-version).
 
 ## Attribution
 

README.md

@@ -41,11 +41,11 @@ Calliope can run on Windows, macOS and Linux. Installing it is quickest with the
 
 See the documentation for more [information on installing](https://calliope.readthedocs.io/en/stable/user/installation.html).
 
-Several easy to understand example models are [included with Calliope](calliope/example_models) and accessible through the `calliope.examples` submodule.
+Several easy to understand example models are [included with Calliope](https://github.com/calliope-project/calliope/tree/main/src/calliope/example_models) and accessible through the `calliope.examples` submodule.
 
 The [tutorials in the documentation run through these examples](https://calliope.readthedocs.io/en/stable/user/tutorials.html). A good place to start is to look at these tutorials to get a feel for how Calliope works, and then to read the "Introduction", "Building a model", "Running a model", and "Analysing a model" sections in the online documentation.
 
-More fully-featured examples that have been used in peer-reviewed scientific publications are available in our [model gallery](https://www.callio.pe/model-gallery/).
+More fully-featured examples that have been used in peer-reviewed scientific publications are available in our [model gallery](https://www.callio.pe/research/#models).
 
 ## Documentation
 
@@ -66,7 +66,7 @@ See our [contribution guidelines](https://github.com/calliope-project/calliope/b
 
 ## What's new
 
-See changes made in recent versions in the [changelog](https://github.com/calliope-project/calliope/blob/main/changelog.rst).
+See changes made in recent versions in the [changelog](https://github.com/calliope-project/calliope/blob/main/CHANGELOG.md).
 
 ## Citing Calliope
 

docs/installation.md

@@ -82,7 +82,7 @@ IBM offer academic licenses for CPLEX. Refer to the IBM website for details.
 
 ## Python module requirements
 
-Refer to [requirements.txt](https://github.com/calliope-project/calliope/blob/main/requirements.txt) in the Calliope repository for a full and up-to-date listing of required third-party packages.
+Refer to the [requirements file](https://github.com/calliope-project/calliope/blob/main/requirements/base.txt) in the Calliope repository for a full and up-to-date listing of required third-party packages.
 
 Some of the key packages Calliope relies on are: