How to create docs with pdoc

Keybinding Markup

# Pdoc

- https://pdoc.dev/
- https://pdoc3.github.io/pdoc/

# Install using PIP

```
pip3 install pdoc3
```

# Install Visual Studio Code Plugin

https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring

This plugin will automatically generate templates for documentations like this:

```
"""Parse and join the data CSV and the metadata CSV

Args:
            fpath_data (str): file path for the data CSV
            fpath_meta (str): file path for the metadata CSV
            taxon_name (str, optional): name of the taxon column exactly as in the data CSV.
            Defaults to 'Phylum'.
            time_column_name (str, optional): name of the timestamp column exactly as in the metadata CSV. Defaults to 'Age (days)'.
            time_column_name_out (str, optional): name of the timestamp column in the return data frame. Defaults to 'day'.
            k_years (int, optional): in the return data frame, we keep timestamps up to the number of years specified. Defaults to 2.
            k_biomes (int, optional): in the return data frame, we keep the k most abundant biomes. Defaults to 15.

Returns:
            pandas.DataFrame: parsed, cleaned data frame
        """
```

# Generate docs from the command line

Say me code lives in a directory called `qbiome`. Run the command below:

```
pdoc --html qbiome/ --output-dir docs --force
```

# Adding mathematical equations

```
pdoc --html dir/ -o docs/ -c latex_math=True -f
```

Use \$\$ \$\$ for block equations or backslash bracket  for inline

# Dark mode

To get dark mode (see example [here](/uploads/hypothesis.html)):

```
pdoc --html hypothesis/ -o docs/ -c latex_math=True -f --template-dir custom_templates/
```

where we first copy the contents of the dfault pdoc/templates to custim_templates, and then use this  [css.mako](/uploads/css.mako). You can update the logo.mako as 
```
<img src="logo.png" alt="drawing" style="width:400px;"/>
```
and the credits.mako as 
```
Author: Lynn Zheng, Jin Li and Ishanu Chattopadhyay <a href="https://zed.uchicago.edu"> Zero Knowledge Discovery, University of Chicago</a>. Email: ishanu@uchicago.edu
```

This creates a directory `docs/qbiome`. Host `docs/qbiome/index.html` on GitHub Pages and you have your documentation website.

Uploading file...

Header

Edit message:

Cancel

Editing How to create docs with pdoc

Header

Sidebar