Jean Le Tavernier, Public domain, via Wikimedia Commons
Neat docstring format for building API references
- Overview
- Usage
- Demo
- Docstring format
- Config file
- Command-line interface
- Application programming interface
- API reference coverage
- API reference rendering and navigation
- Miscellaneous
- Testing and contributing
- Installation
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
[params]
- a: left-hand integer operand
- b: right-hand integer operand
[returns]
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.
[params]
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.
[returns]
This section describes the value to return.
[yields]
This section describes the value to yield.
[raises]
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:
- Modules: A module represents the main unit of a codebase.
- Fields: Variables and constants.
- Functions
- Classes
- Regular classes
- Fields: Also referred to as
class attributes. - Properties:
Getters,setters, anddeleters. - Methods
- Regular methods
- Static methods
- Class methods
- Fields: Also referred to as
- Enumerations
- Fields: Also referred to as
enum members.
- Fields: Also referred to as
- Named Tuples
- Fields
- Regular classes
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
- [1] - The package directory:
pkg_dir = 'src/package'. - [2] - The API directory:
api_dir = 'docs/api'. - [3] - Home page for the API reference.
- [4] - Overview page for the
package.module1module. - [5] - Page for documenting
MyClass1exposed inpackage.module1. - [6] - Page for documenting public fields (variables and constants) exposed in
package.module1. - [7] - Page for documenting public functions exposed in
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
deactivateMikeDoc is cross-platform. It is built on Ubuntu and should work on Python 3.5 or newer.
python -m venv venv
source venv/bin/activatepip install mikedocpip install mikedoc --upgrade --upgrade-strategy eagerdeactivateHello world, I'm Alex, a tech enthusiast ! Feel free to get in touch with me !
