TDM 30100: Project 4 — 2023

Motivation: Documentation is one of the most critical parts of a project. There are so many tools that are specifically designed to help document a project, and each have their own set of pros and cons. Depending on the scope and scale of the project, different tools will be more or less appropriate. For documenting Python code, however, you can’t go wrong with tools like Sphinx, or pdoc.

Context: This is the second project in a 2-project series where we explore thoroughly documenting Python code, while solving data-driven problems.

Scope: Python, documentation

Learning Objectives

  • Use Sphinx to document a set of Python code.

  • Use pdoc to document a set of Python code.

  • Write and use code that serializes and deserializes data.

  • Learn the pros and cons of various serialization formats.

Make sure to read about, and use the template found here, and the important information about projects submissions here.

Dataset(s)

The following questions will use the following dataset(s):

  • /anvil/projects/tdm/data/apple/health/watch_dump.xml

Setting Up:

This project will be building off of the work we did last week in Project 03. Please feel free to copy over your code so that you can continue working on it. I would recommend doing this in a new Project 04 directory so that you have two completely distinct versions of this project, one for each submission you will need for this class. If you did not complete Project 03, please go back to that project and understand it before attempting this one. You are also encouraged to talk (early in the week) with one or more of the TAs if you are confused.

Question 1 (4 pts)

  1. Add autodoc configuration to your conf.py file, regenerate your documentation, and take a picture of the resulting webpage.

The pdoc package was specifically designed to generate documentation for Python modules using the docstrings in the module. As you may have noticed, this is not "native" to Sphinx.

Sphinx has extensions. One such extension is the autodoc extension. This extension provides the same sort of functionality that pdoc provides natively.

To use this extension, modify the conf.py file in the docs/source folder.

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc'
]

Next, update your index.rst file so autodoc knows which modules to extract data from.

.. project4 documentation master file, created by
   sphinx-quickstart on Wed Sep  1 09:38:12 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to project4's documentation!
====================================

.. automodule:: firstname_lastname_project04
    :members:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   README

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

In a new bash cell in your notebook, regenerate your documentation. Check out the resulting index.html page, and click on the links. Not too bad!

Items to submit

Question 2 (4 pts)

  1. Import the appropriate extensions so that Sphinx recognizes Google_style docstrings.

  2. Create a new function, graph_avg_heart_rate, that graphs the average heart rate for all dates in our watch data.

  3. Regenerate your documentation, and take a picture of the resulting webpage.

Okay, while the documentation looks pretty good, clearly, Sphinx does not recognize Google style docstrings. As you may have guessed, there is an extension for that.

Add the napoleon extension to your conf.py file.

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon'
]

Next, we would like you to write a new function called graph_average_heart_rate that graphs the average heart rate for all dates in our watch data. The type of graph your function generates is up to you, but it should be a meaningful and well-labeled graphic that demonstrates something about the data (i.e. shape, outliers, etc.). Make sure to include a Google style docstring for your function.

When writing more complicated functions, think about the steps they need to do. For example, our function needs to do the following:

for each date in our data:
- get the records for that date
- get the average heart rate for that date
- add the average heart rate to a list of averages

Then, finally, graph the list of averages.

I think simply by looking at this pseudocode in combination with the functions you wrote for previous questions, you should be able to get a good idea of how to structure and write this function.

In a new bash cell in your notebook, regenerate your documentation. Check out the resulting index.html page, and click on the links. Much better! Take a final screenshot of your index.html page, and include it in this question’s submission section

Items to submit

  • function graph_avg_heart_rate with a Google style docstring.

  • Regenerated final documentation to recognize Google style docstrings.

  • Screenshot labeled "question05_results". Make sure you include your screenshot correctly.

Items to submit

For this project, please submit the following files:

  • The .ipynb file with:

  • all functions throughout the project, demonstrated to be working as expected.

  • every different bash command used to call Sphinx at least once

  • screenshots whenever we asked for them in a question

  • An .html file with your newest set of documentation.

Please make sure to double check that your submission is complete, and contains all of your code and output before submitting. If you are on a spotty internet connection, it is recommended to download your submission after submitting it to make sure what you think you submitted, was what you actually submitted.

In addition, please review our submission guidelines before submitting your project.