What are the best practices for easily accessible GIS code documentation in Python?

1 Use docstrings and comments

Docstrings and comments are the basic elements of Python code documentation. Docstrings are special strings that describe the purpose, parameters, and output of a function, class, or module. They are enclosed in triple quotes and appear right after the definition of the object. Comments are any text that follows a hash sign (#) and is ignored by the interpreter. They are used to explain the logic, assumptions, or context of a code block. Both docstrings and comments should be concise, informative, and relevant to the code. You can use a standard format for docstrings, such as Google, NumPy, or reStructuredText, to make them easier to read and generate documentation.

2 Use Sphinx and extensions

Sphinx is a powerful tool that can generate HTML, PDF, or other formats of documentation from your docstrings and other sources. It can also create cross-references, indexes, tables of contents, and search functions for your documentation. Sphinx supports several extensions that can enhance your documentation, such as sphinx-automodapi, which can automatically document your modules and submodules; sphinx-gallery, which can create gallery pages from your scripts and notebooks; and sphinx-rtd-theme, which can give your documentation a modern and responsive look.

4 Use GitHub and GitHub Pages

GitHub is a popular platform for hosting and collaborating on code projects. You can use GitHub to store, manage, and version your GIS code and documentation. You can also use GitHub Pages to publish your documentation online for free. GitHub Pages can automatically build and deploy your documentation from a branch or a folder of your repository, using Sphinx or Jupyter notebooks as sources. You can also use a custom domain name for your documentation site.

5 Use Read the Docs

Read the Docs is a service that can host and build your documentation from your GitHub, GitLab, or Bitbucket repositories. It can automatically update your documentation whenever you push changes to your code or documentation. It can also handle multiple versions, languages, and formats of your documentation. Read the Docs integrates well with Sphinx and Jupyter notebooks, and offers a variety of themes and features for your documentation site.

6 Use good practices and standards

To create easily accessible GIS code documentation in Python, you should adhere to some general good practices and standards. Consider who will use, read, or benefit from your documentation, and tailor your language, tone, and level of detail accordingly. Utilize the same format, style, and conventions throughout your documentation, and avoid ambiguity, redundancy, or contradiction. Ensure your documentation reflects the current state and functionality of your code, and update it whenever you make changes or improvements to your code. Make sure to cover all aspects and features of your code with examples, screenshots, or links to illustrate your points. Use simple, precise, and grammatical language to make your documentation clear and organized logically and hierarchically.

7 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?