How to add to or update the MapReader documentation
MapReader’s documentation is generated using Sphinx and hosted on Read the docs. There are a number of ways you can contribute to our documentation, these include:
Updating or adding clarity to existing documentation.
Fixing errors in existing documentation (e.g. typos or code inconsistencies).
Creating new worked examples which showcasing MapReader use cases.
Documentation dependencies
If you would like to edit or add to the MapReader documentation, you will need to install sphinx
along with the packages detailed in MapReader/docs/requirements.txt
.
To do this (assuming you have installed MapReader from source, as per our Installation instructions), use:
conda activate mapreader
pip install sphinx
pip install -r MapReader/docs/requirements.txt
Note
You may need to change the file path depending on where your MapReader directory is saved.
Writing in reStructuredText
reStructuredText (rst) is the default plaintext markup language used by Sphinx and is the primary language used throughout our documentation. If you have never used or written in rst, this primer is a great place to start. There are also numerous other rst ‘cheatsheets’ (e.g. here and here) available online, so have a google.
To help make your rst files easier to read and review, please start each new sentence on a new line. This will make no difference to how the text is displayed, but will make it much easier to read when reviewing changes in a pull request.
Before you begin
Before you begin making your changes to the documentation, you should ensure there is a corresponding issue on the MapReader repository (or create one if needed). You should then either assign yourself to the issue or comment on it saying you will be working on making these changes.
You will then need to fork the MapReader repository in order to make your changes.
Please also be aware that API documentation is auto-generated by the sphinx-autoapi
extension.
If you would like to change something in the API documentations, you will need to change the docstrings in the code itself.
Head to our guide to updating the MapReader code if you would like to have a go at this, or, if you feel hesitant about making code changes, create an issue detailing the changes you think need making.
Style guide
Use the following heading styles:
Use
.. code-block:: <lang>
to create code blocks formatted as per your given langauge (replace<lang>
with the language you will be writing in). e.g... code-block:: python
will create a code block with python formatting.Use
Link title <http://www.anexamplelink.com>`__
to link to external pages.Use
.. contents::
to automatically generate a table of contents detailing sections within the current page. e.g.
.. contents:: Table of contents
:depth: 1
Use
.. toc-tree::
to generate a table of contents (toc) linking to other pages in the documentation. e.g.
.. toc-tree::
:maxdepth: 1
page1
page2
Use
.. note::
and.. warning::
to add notes and warnings.
If you are adding to the User Guide, you may also want to consider how you structure your documentation to ensure clarity.
So far, we have chosen to first give a generic example of how to use the code, followed by a specific example labelled as #EXAMPLE
. e.g.
Generic example:
from mapreader import loader
my_files = loader("./path/to/files/*png")
Followed by specific example:
#EXAMPLE
my_files = loader("./maps/*.png")
When you are finished
Once you are happy with the changes you have made, please create a new pull request to let us know you’d like us to review your work.
If possible, please link your pull request to any issue(s) your changes fix/address and write a thorough description of the changes you have made.