Jean Le Tavernier, Public domain, via Wikimedia Commons
Neat docstring format for building API references
MikeDoc (pronounced /ˈmaɪkdɒk/) is a neat docstring format for building API references.
Its eponymous lightweight reference library exposes functions and classes for parsing docstrings as well as traversing any arbitrary Python codebase, iteratively yielding the fields, classes, and functions contained within each module.
The library also offers to generate API references consisting of Markdown documents from the command line or programmatically. Once generated, an API reference can be browsed offline with a Markdown reader or online with GitHub or another platform.
MikeDoc's Python package can be used both as a tool to generate API references, or as a library to traverse an arbitrary Python codebase (for example, to create a new tool to generate API references).
From the command-line:
# cd in the project root dir
$ cd /path/to/project
# create the config file
$ mikedoc init
Config file 'mikedoc.braq' created !
# build the api reference
$ mikedoc build
API reference built in 'docs/api' !
Programmatically:
from mikedoc import build
# config
root_dir = "/path/to/project"
project_name = "ProjectName"
project_url = "/README.md"
pkg_dir = "src/package"
api_dir = "docs/api"
# build the API reference
build(root_dir, project_name, project_url, pkg_dir, api_dir)
The following script uses three loops to access the methods of all classes in order to print their docstrings:
import mikedoc
root_dir = "/path/to/project"
pkg_dir = "src/package"
# === LOOP 1 === Accessing each module
for module_info, members in mikedoc.browse(root_dir, pkg_dir):
# 'module_info' is a namedtuple and 'members' is an iterator
# to iterate through fields, funcs, and classes in the module
assert isinstance(module_info, mikedoc.ModuleInfo)
# === LOOP 2 === Accessing each member in the module
for member_info in members:
# 'member_info' is a namedtuple
assert isinstance(member_info, mikedoc.MemberInfo)
# skip if member isn't a class
if not member_info.is_class:
continue
# 'class_members' is a sequence of namedtuples
class_members = member_info.members
# === LOOP 3 === Accessing each member in the class
for class_member_info in class_members:
# class_member_info is a namedtuple
assert isinstance(class_member_info, mikedoc.ClassMemberInfo)
# print the parsed docstring of each method in the class
if class_member_info.is_method:
# get the docstring
docstring = class_member_info.doc
# parse the docstring
data = mikedoc.parse_docstring(docstring)
# print the docstring
print(docstring)
from mikedoc import parse_docstring
docstring = """
A multiline description
for a *function* that adds two numbers
[param]
- a: left-hand integer operand
- b: right-hand integer operand
[return]
Sum of `a` and `b`"""
# returns a dictionary
data = parse_docstring(docstring)
print(data)
The code above would output this:
{'': 'A multiline description\nfor a *function* that adds two numbers',
'param': {'a': 'left-hand integer operand',
'b': 'right-hand integer operand'},
'return': 'Sum of `a` and `b`'}
MikeDoc's API reference itself can serve as an explorable demo as well as those from other projects such as Braq and Paradict.
| Project | API reference |
|---|---|
| MikeDoc: Neat docstring format for building API references | mikedoc/docs/api |
| Braq: Customizable data format for config files, AI prompts, and more | braq/docs/api |
| Paradict: Streamable multi-format serialization with schema | paradict/docs/api |
The format can be summarized as follows:
def arbitrary_function(a, b):
"""
A description of the **function** that
might span multiple lines.
[param]
Optional short text to introduce parameters.
- a: Short or long description that might
span multiple lines.
- b: Short or long description that might
span multiple lines.
[return]
This section describes the value to return.
[yield]
This section describes the value to yield.
[except]
Optional short text to introduce
exceptions that might be raised.
- Exception: Short or long description that might
span multiple lines.
"""
...
The MikeDoc format uses Braq to structure the docstring into sections. The unnamed section represents the description of the function/class/method. The param and except sections are hyphenated key-value pairs to describe parameters and exceptions (which might be raised), respectively.
The docstring format allows reasonable use of Markdown like emphasis and links. It is recommended to keep it simple.
To be able to build a reference API for an arbitrary Python project, a mikedoc.braq config file should be placed at the root of the codebase directory. The file can be generated with the init command from the CLI.
Here is the mikedoc.braq config file placed at the root of MikeDoc itself:
# project name
project_name = 'MikeDoc'
# project's website or README
project_url = '/README.md'
# package directory (relative path)
pkg_dir = 'mikedoc'
# API directory (relative path)
api_dir = 'docs/api'
For a project named my-project, whose package (my_project) isn't placed directly at the root of the project directory but inside the src folder, the pkg_dir would contain the string 'src/my_project'.
Only the slash character is allowed as path separator in the config file.
For most cases, the generated config file doesn't need to be edited.
The init and build commands are all you need:
# cd in the project root dir
$ cd /path/to/project/root
# create the config file
$ mikedoc init
Config file 'mikedoc.braq' created !
# build the api reference
$ mikedoc build
API reference built in 'docs/api' !
For most cases, the generated config file doesn't need to be edited.
Explore the API Reference !
An API reference generated by this tool would comprehensively cover various elements of a Python codebase, including:
class attributes.Getters, setters, and deleters.enum members.MikeDoc generates Markdown files that can be rendered and browsed online on GitHub or explored offline with a Markdown reader. Markdown files are organized in directories that mirror the organization of the codebase.
project
mikedoc.braq
src
package [1]
module1.py
sub_package
module2.py
docs
api [2]
README.md [3]
MIKEDOC
modules
package
module1
README.md [4]
class-MyClass1.md [5]
fields.md [6]
funcs.md [7]
sub_package
module2
README.md
class-MyClass2.md
fields.md
funcs.md
pkg_dir = 'src/package'.api_dir = 'docs/api'.package.module1 module.MyClass1 exposed in package.module1.package.module1.package.module1.Navigation between pages relies on links all relative to the root directory. These relative links are prefixed with a slash
/.
Miscellaneous stuff...
In Python, underscores are very common in identifiers. When these identifiers are rendered as underlined links, it becomes hard to notice the underscores.
To change the visibility of underlines on links that are adjacent to text, check the GitHub accessibility settings.
Feel free to open an issue to report a bug, suggest some changes, show some useful code snippets, or discuss anything related to this project. You can also directly email me.
Following are instructions to setup your development environment
# create and activate a virtual environment
python -m venv venv
source venv/bin/activate
# clone the project then change into its directory
git clone https://github.com/pyrustic/mikedoc.git
cd mikedoc
# install the package locally (editable mode)
pip install -e .
# run tests
python -m unittest discover -f -s tests -t .
# deactivate the virtual environment
deactivate
MikeDoc is cross-platform. It is built on Ubuntu and should work on Python 3.5 or newer.
python -m venv venv
source venv/bin/activate
pip install mikedoc
pip install mikedoc --upgrade --upgrade-strategy eager
deactivate
Hello world, I'm Alex, a tech enthusiast ! Feel free to get in touch with me !
FAQs
Neat docstring format for building API references
We found that mikedoc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.
Security News
Research
The Socket Research Team uncovered a malicious Python package typosquatting the popular 'fabric' SSH library, silently exfiltrating AWS credentials from unsuspecting developers.