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.

Here is an example of a Python function with its MikeDoc docstring:

  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.
      """
      ...

Here is the content of the `mikedoc.dict` config file [4] of the MikeDoc project 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'

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.

MikeDoc's Python package is available on PyPI and you can already explore its own API reference on GitHub [5].

Let me know what you think of this project.

[1] https://en.wikipedia.org/wiki/Docstring

[2] https://news.ycombinator.com/item?id=21289832 [Four kinds of documentation (divio.com)]

[3] https://github.com/pyrustic/braq

[4] https://news.ycombinator.com/item?id=38684724

[5] https://github.com/pyrustic/mikedoc/?tab=readme-ov-file#demo