Skip to main content

Generate markdown documentation for your Python scripts.Like Sphinx, but simpler and directly compatible with GitHub.

Project description


Generate markdown documentation for your Python scripts' code comments that is compatible with GitHub. It's like Sphinx, but with simpler requirements and results. It's also not as flexible as Sphinx and is mainly useful for scripts containing only a few classes.

For example output, see the code documentation for this module.


pip3 install py-md-doc


To generate the documentation for this module:

  1. Clone this repo.
  2. cd path/to/py_md_doc (Replace path_to) with the actual path to this repo.)
  3. python3

To generate documentation for your own module:

from py_md_doc import PyMdDoc
from pathlib import Path

md = PyMdDoc(input_directory=Path("my_module/my_module"), files=[""], metadata_path="metadata.json")

For the full API, read this.

Code comments format

  • One class per file.
  • Class descriptions begin and end with """ immediately after the class definition.
  • Class variables begin with """:class_var and end with """ and must be before the constructor declaration. The line immediately after them is the variable declaration.
  • Fields begin with """:field and end with """ in the constructor. The line immediately after them is the field declaration.
  • Function descriptions begin and end with """ immediately after the function definition.
    • Function parameter descriptions are lines within the function description that begin with :param
    • Function return description are lines within the function description that begin with :return:
  • Function names that begin with _ are ignored.
  • The code for PyMdDoc as well as the code examples below use type hinting. You do not need type hinting in your code for PyMdDoc to work properly.
class MyClass:
    This is the class description.

    This is a class variable.
    CLASS_VAR: int = 0

    def __init__(self):
        The ID of this object.
        self.val = 0

    def set_val(self, val: int) -> None:
        Set the val of this object.

        :param val: The new value.

        self.val = val

    def get_val(self) -> int:
        :return The value of this object.
        return self.val

    def _private_function(self) -> None:
        This won't appear in the documentation.

  • Enum values are documented by commenting the line next to them.
from enum import Enum

class MyEnum(Enum):
    a = 0  # The first value.
    b = 1  # The second value.

Metadata file

You can add an optional metadata dictionary (see the constructor).

A metadata file is structured like this:

    "Constructor": {
      "description": "",
      "functions": ["__init__"]
    "Documentation Generation": {
      "description": "Use these functions to generate your documentation.",
      "functions": ["get_docs", "get_doc"]
    "Helper Functions": {
      "description": "These functions are used in `get_docs()`. You generally won't need to call these yourself.",
      "functions": ["get_class_description", "get_class_variables", "get_function_documentation", "get_enum_values", "get_fields"]
  • The top-order key of the dictionary ("PyMdDoc") is the name of the class. You don't need to add every class that you wish to document. If the class is not listed in metadata.json but is listed in the files parameter, its functions will be documented in the order they appear in the script.
  • Each key in the class metadata ("Constructor", "Documentation Generation", "Helper Functions") is a section.
    • Each section name will be a header in the document, except for "Constructor" and "Ignore".
    • Any function in the "Ignore" category won't be documented.
    • Each section has a "description" and a list of names of "functions". The functions will appear in the section in the order they appear in this list.
  • If the class name is listed in metadata.json and a function name can't be found in any of the section lists, the console will output a warning. For example, if you were to add a function named new_function() to PyMdDoc, you'd have to add it to a section in the metadata file as well because PyMdDoc is a key in the metadata dictionary.


  • This script is for class objects only and won't document functions that aren't in classes:
def my_func():
    This function will be ignored.

class MyClass:
    This class will be in the documentation.

    def class_func(self):
        This function will be in the documentation.

def another_my_func():
    This function will be erroneously included with MyClass.
  • Functions can be grouped and reordered into categories, but classes and fields are always documented from the top of the document to the bottom:
class MyClass:
    This class will documented first.

    def class_func(self):
        This function will be documented first.

    def another_class_func(self):
        This function will be documented second.

class AnotherClass:
    This class will be documented second.


To create API documentation for a script that contains only variables (no classes or functions), use VarDoc.



  • Added optional parameter import_prefix to PyMdDoc.get_doc() and PyMdDoc.get_docs().


  • Fixed: Various issues with functions not appearing correctly or not appearing at all with get_docs_with_inheritance().
  • Fixed: There is no ## Functions header if there aren't also fields.


  • Fixed: get_docs_with_inheritance() returns the abstract class document for a child class if there are any @final attribute headers.


  • Added: get_docs_with_inheritance() Basic support for API documentation with class inheritance.


  • Added a header to documents generated by VarDoc.


  • Added: VarDoc Create documentation of variables.


  • Don't italicize section descriptions.
  • Automatically generate a table of contents it [TOC] is present in the document.


  • Fixed: Crash when writing text if the text has non-ASCII characters.


  • Fixed: Data from hidden classes (classes with names that begin with _) is included in the documentation, either within the main class documentation or above it without a header. Now, it's never included.


  • Fixed: Class variable types are sometimes parsed incorrectly.


  • Fixed: Category description formatting breaks if there are line breaks.


  • Fixed: Class variables aren't included in documentation.


  • Fixed: Can't find :return decorators (expecting only :return:).
  • Fixed: Unhandled exception if there's more than one class in the file.
  • Added: social.jpg


  • Added: Special category Ignore to metadata. Functions in this category will be ignored.


  • All functions that have parameters with default values now have two example code strings: a "short" example (parameters with default values aren't included) and a "long" example (all parameters with default values are explicitly assigned).
  • Added default values to parameter table.
  • Added: to hold parameter information.
  • Moved the documentation generation code for this module to to avoid import path errors.


  • Added support for class variables.
  • Added much clearer code examples for function documentation.
  • Added parameter types to the function parameter tables.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for py-md-doc, version 0.2.5
Filename, size File type Python version Upload date Hashes
Filename, size py_md_doc-0.2.5.tar.gz (15.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page