Hi HN ! I'm Alex, a tech enthusiast. I am excited to show you MikeDoc (<a href="https://github.com/pyrustic/mikedoc">https://github.com/pyrustic/mikedoc</a>), a docstring [1] format for building API references [2]. This project is a major iteration of an internal tool that helped me generate API references for my projects as Markdown files that can be browsed offline or online.<p>To generate such Markdown files, the tool iterates through the modules of a given Python codebase and parses the docstrings. The MikeDoc format is designed so that a typical docstring looks neat, is easy to parse, and uses Markdown syntax. I found it natural to divide the docstring into sections with headers surrounded by square brackets [3]. Depending on the section type, the content is either prose or hyphenated key-value pairs with an optional introductory paragraph.<p>Here is an example of a Python function with its MikeDoc docstring:<p><pre><code> def sum(a, b):
"""
This function returns the sum of two integers.
[param]
- a: Left-hand integer operand.
- b: Right-hand integer operand.
[return]
Sum of `a` and `b`.
[except]
- OverflowError: Exception raised if either `a` or `b` is too big.
- IntegerError: Exception raised if either `a` or `b` isn't an integer.
"""
...
</code></pre>
Although MikeDoc offers to generate an API reference programmatically, it also has a minimalist command line interface that offers to do the same thing but without friction thanks to the `init` and `build` commands. The `init` command generates a config file that does not need to be modified in most cases, and the `build` command generates the API reference based on the contents of the config file.<p>Here is the content of the `mikedoc.dict` config file [4] of the MikeDoc project itself:<p><pre><code> # 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'
</code></pre>
As a neat docstring format, MikeDoc can extend existing documentation generators such as Sphinx and can be used with any programming language that supports concepts such as function parameters, return value, and exceptions.<p>As a standalone tool, MikeDoc would fit well into any Python project whose API reference needs to be embedded in the root directory and browsable offline and online without config changes.<p>MikeDoc's Python package is available on PyPI and you can already explore its own API reference on GitHub [5].<p>Let me know what you think of this project.<p>[1] <a href="https://en.wikipedia.org/wiki/Docstring" rel="nofollow">https://en.wikipedia.org/wiki/Docstring</a><p>[2] <a href="https://news.ycombinator.com/item?id=21289832">https://news.ycombinator.com/item?id=21289832</a> [Four kinds of documentation (divio.com)]<p>[3] <a href="https://github.com/pyrustic/braq">https://github.com/pyrustic/braq</a><p>[4] <a href="https://news.ycombinator.com/item?id=38684724">https://news.ycombinator.com/item?id=38684724</a><p>[5] <a href="https://github.com/pyrustic/mikedoc/?tab=readme-ov-file#demo">https://github.com/pyrustic/mikedoc/?tab=readme-ov-file#demo</a>