Background:

My group is working on a project and I am creating the documentation that will also create a html documentation (like pdoc).

Due to how the project evolved. The code is across a number of files and places-Google Colab, Jupyter Notebook, Azure Notebook.

Current work around/workflow:

Created a google colab notebook. And I have been creating Text blocks for some of the documentation. And whenever there is code, I copy and paste it into a code block and create a doc string (“”” code explaination/summary”””)

Download file from Colab as .py, then on command line ‘’’pdoc —-html file.py’’’

Issues

1. Some of the code is not executable, for example the code block to doc the Colab notebook to google drive. This is something that will continue. Later on there will be code that isn’t going to work, I just want to include the information associated with it for the html documentation

2. The project is still in progress. So if there are going to be any changes in the real code, I will have to manually find the changes and copy the code and make edits.

generalized example

File set up: A data profiling document on jupyter notebook

Data cleaning file on Colab

Config file on azure

Experiment 1,2,3… on azure

current google Colab documentation file

TEXTBLOCK

Project Goal

Blah blah blah

——

brief explanation of what can be found in this documentation

——

CODE BLOCK Code to doc Colab notebook to google drive

TEXTBLOCK

Data Profiling

Brief summary of file

CODEBLOCK importing packages Read data in def foo() “”” brief summary of function

“”” Blah blah blah Return

TEXTBLock and code blocks for profiling

TEXTBLOCK

Data cleaning

Brief summary of what’s done in this file

And so on and so on

QUESTION

1. Is there a different document generator that I can use that would ignore errors. I don’t want this Colab file to actually read in the data. And later on the experiment files cannot even be executed on Colab or my own laptop.

2. Is there a better way of doing this? I’m still in the very early parts of part. So if there is a better documentation generator or practice that would avoid the problems that I already can see and other issues that you may already know from your experience.