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.