Generating documentation with Sphinx

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

Setup

Navigate to the average-squares folder that you used in the previous exercise.

(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 repository 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 within 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.
Run python -m http.server -d _build/html/ and open the link shown by this command 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 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-COMP0233-24-25/RSE-Classwork#20

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 (linked also on the optional resources for this week).

Sample solution as changes made on sphinx-setup branch

UCL-COMP0233-24-25 / RSE-Classwork