pdoc
pdoc is a Python package that auto-generates API documentation straight from the Python code itself. It is a simple, straightforward tool that generates HTML documentation, with a few extra features that allow for more advanced customization.
Below is an arbitrary example of a small Python module.
"""
This Python module is a fake module that is used to test the pdoc package.
It is useful to be able to look at a set of example Python code, and see how
the Python code is translated to HTML.
"""
import pandas as pd
import numpy as np
import requests
def scrape_website(url: str) -> requests.models.Response:
"""
Given a URL, return the `requests` response object.
Args:
url (str): URL to scrape.
Returns:
requests.models.Response: `requests` response object.
"""
resp = requests.get(url)
return resp
def are_pages_different(page1: requests.models.Response, page2: requests.models.Response) -> bool:
"""
Given two `requests` response objects, return True if they are different, False otherwise.
Args:
page1 (requests.models.Response): First page to compare.
page2 (requests.models.Response): Second page to compare.
Returns:
bool: True if the pages are different, False otherwise.
"""
return page1.text != page2.text
class WebPage:
def __init__(self, resp: requests.models.Response):
"""
Given a `requests` response object, initialize a WebPage object.
Args:
resp (requests.models.Response): `requests` response object.
Raises:
ValueError: If the `requests` response object returned a non 200 status code.
"""
if resp.status_code != 200:
raise ValueError('The response code is not 200.')
else:
self.resp = resp
def is_datamine_affiliated(self, case_insensitive: bool = False) -> bool:
"""
Returns True if the WebPage is affiliated with Datamine, False otherwise.
A WebPage is affiliated with Datamine if HTML contains the string "Purdue"
and the string "datamine". By default the search is case-insensitive.
Args:
case_insensitive (bool, optional): Whether or not the search is case-sensitive or not. Defaults to False.
Returns:
bool: Whether the WebPage is affiliated with The Data Mine or not.
"""
if not case_insensitive:
if 'purdue' in self.resp.text.lower() and 'datamine' in self.resp.text.lower():
return True
return False
else:
if 'Purdue' in self.resp.text and 'datamine' in self.resp.text:
return True
return FalseThis Python module follows the Google Styleguide for comments and docstrings. By default, pdoc won’t assume any particular style for the docstrings. However, we can use the -d flag to specify the "google" style.
mkdir $HOME/my_documentation
python -m pdoc -d google -o $HOME/my_documentation/ mymodule.pyHere, the -d option specifies that we are using Google-style docstrings, and to format HTML appropriately. The -o option tells pdoc to output the documentation to the specified directory, $HOME/my_documentation.
|
Note that the order of the arguments does matter. In other words, the value being passed with the In that case, "google" would be passed to |
The resulting HTML documentation looks clean and informative.