Generating documentation with Sphinx

[HChughtai]

This exercise will introduce you to the basics of Sphinx using the same code you looked at in the previous exercise (#100).

Setup

• Navigate to the week06/average-squares-example folder that you used in the previous issue.
• (Note: You will be able to complete this exercise even if you haven't finished the previous one - the only difference is that some of your generated documentation will be different)

Understanding

• This folder contains a simple project that could do with some documentation.
  • The code is within the average_squares folder and your task is to generate some documentation to go alongside it.

Exercises

Getting started with Sphinx

• Ensure that you have Sphinx installed for your system
• Create a docs folder alongside the average_squares folder - this is where your documentation for the project will be stored
• From within the docs folder run sphinx-quickstart to generate the scaffolding files that Sphinx needs
  • Ensure that you select no for Separate source and build directories - this should be the default but if chosen incorrectly will mean your folder structure won't match up to the instructions below
  • You can accept the defaults and enter sensible information for the other fields.
• Run sphinx-build . _build/html or make html to generate html docs
• Open _build/html/index.html to see the built documentation in a browser

Modifying index.rst

• Open the index.rst file - this is the master document that serves as the entrypoint and welcome page to the documentation.
• Add a line or two about the purpose of the project
• Save and rebuild the documentation - verify that it builds correctly

Adding content and structure

• In the docs folder create a subfolder called content.
• Within docs/content create a file called average-squares-docs.rst with the following contents:

Average Squares Documentation
=============================

• Update the toctree directive in index.rst so that this new file is included.
• Rebuild the documentation and verify that this file is now linked to.

Using Docstrings to create documentation

As you saw in the previous exercise (#100) the code in this project contains some docstrings - let's show this in our Sphinx generated documentation

• Follow the instruction on the Sphinx getting started page to enable the autodoc function
• Can you modify the content/average-squares-docs.rst file to include docstrings from the code automatically?
• Hint: You may find it useful to modify the path setup in docs/conf.py in the following way so it is easier for Sphinx to find the location of the code

# -- Path setup --------------------------------------------------------------

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Updating your PR

Commit the changes to your branch, updating the PR you created in the previous exercise. Add a comment with Answers UCL-RITS/rse-classwork-2020#101

Explore further features of Sphinx

There are many additional features of Sphinx - explore them if you have time. For example:

• Are you able to modify the theme?
• What other Sphinx extensions are available?
• A more extensive introduction to Sphinx is linked to on the Moodle resources.