{"id":21127015,"url":"https://github.com/pyrustic/mikedoc","last_synced_at":"2026-03-06T08:01:56.810Z","repository":{"id":237308198,"uuid":"794271763","full_name":"pyrustic/mikedoc","owner":"pyrustic","description":"Neat docstring format for building API references","archived":false,"fork":false,"pushed_at":"2024-12-10T20:57:55.000Z","size":92,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-08T23:40:38.643Z","etag":null,"topics":["api-reference","codebase","docs-generator","docstring","documentation","python"],"latest_commit_sha":null,"homepage":"https://pyrustic.github.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyrustic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-04-30T19:40:29.000Z","updated_at":"2025-03-21T08:49:10.000Z","dependencies_parsed_at":"2025-07-08T23:43:01.446Z","dependency_job_id":null,"html_url":"https://github.com/pyrustic/mikedoc","commit_stats":null,"previous_names":["pyrustic/mikedoc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pyrustic/mikedoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrustic%2Fmikedoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrustic%2Fmikedoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrustic%2Fmikedoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrustic%2Fmikedoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyrustic","download_url":"https://codeload.github.com/pyrustic/mikedoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrustic%2Fmikedoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30166859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T07:56:45.623Z","status":"ssl_error","status_checked_at":"2026-03-06T07:55:55.621Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-reference","codebase","docs-generator","docstring","documentation","python"],"created_at":"2024-11-20T04:46:16.236Z","updated_at":"2026-03-06T08:01:56.785Z","avatar_url":"https://github.com/pyrustic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI package version](https://img.shields.io/pypi/v/mikedoc)](https://pypi.org/project/mikedoc)\n[![Downloads](https://static.pepy.tech/badge/mikedoc)](https://pepy.tech/project/mikedoc)\n\n\u003c!-- Cover --\u003e\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/pyrustic/misc/master/assets/mikedoc/cover.jpg\" alt=\"Cover image\" width=\"572\"\u003e\n    \u003cp align=\"center\"\u003e \n    \u003ca href=\"https://commons.wikimedia.org/wiki/File:Tavernier_Jean_Mielot.jpg\"\u003eJean Le Tavernier\u003c/a\u003e, Public domain, via Wikimedia Commons\n    \u003c/p\u003e\n\u003c/div\u003e\n\n\u003c!-- Intro Text --\u003e\n# MikeDoc\n\u003cb\u003eNeat docstring format for building API references\u003c/b\u003e\n\n\n## Table of contents\n- [Overview](#overview)\n- [Usage](#usage)\n- [Demo](#demo)\n- [Docstring format](#docstring-format)\n- [Config file](#config-file)\n- [Command-line interface](#command-line-interface)\n- [Application programming interface](#application-programming-interface)\n- [API reference coverage](#api-reference-coverage)\n- [API reference rendering and navigation](#api-reference-rendering-and-navigation)\n- [Miscellaneous](#miscellaneous)\n- [Testing and contributing](#testing-and-contributing)\n- [Installation](#installation)\n\n\n# Overview\n**MikeDoc** (pronounced `/ˈmaɪkdɒk/`) is a neat [docstring](https://en.wikipedia.org/wiki/Docstring) format for building API references.\n\nIts eponymous lightweight reference [library](#installation) exposes functions and classes for parsing docstrings as well as traversing any arbitrary [Python](https://www.python.org/) codebase, iteratively yielding the fields, classes, and functions contained within each module.\n\nThe library also offers to generate API references consisting of [Markdown](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/GitHub) or another platform.\n\n\n# Usage\n**MikeDoc**'s [Python package](#installation) 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).\n\n## Building an API reference\nFrom the command-line:\n\n```bash\n# cd in the project root dir\n$ cd /path/to/project\n\n# create the config file\n$ mikedoc init\nConfig file 'mikedoc.kvf' created !\n\n# build the api reference\n$ mikedoc build\nAPI reference built in 'docs/api' !\n```\n\nProgrammatically:\n```python\nfrom mikedoc import build\n\n# config\nroot_dir = \"/path/to/project\"\nproject_name = \"ProjectName\"\nproject_url = \"/README.md\"\npkg_dir = \"src/package\"\napi_dir = \"docs/api\"\n\n# build the API reference\nbuild(root_dir, project_name, project_url, pkg_dir, api_dir)\n```\n## Traversing a codebase\nThe following script uses three loops to access the methods of all classes in order to print their docstrings:\n\n```python\nimport mikedoc\n\nroot_dir = \"/path/to/project\"\npkg_dir = \"src/package\"\n\n# === LOOP 1 === Accessing each module\nfor module_info, members in mikedoc.browse(root_dir, pkg_dir):\n    # 'module_info' is a namedtuple and 'members' is an iterator\n    # to iterate through fields, funcs, and classes in the module\n    assert isinstance(module_info, mikedoc.ModuleInfo)\n\n    # === LOOP 2 === Accessing each member in the module\n    for member_info in members:\n        # 'member_info' is a namedtuple\n        assert isinstance(member_info, mikedoc.MemberInfo)\n        # skip if member isn't a class\n        if not member_info.is_class:\n            continue\n        # 'class_members' is a sequence of namedtuples\n        class_members = member_info.members\n\n        # === LOOP 3 === Accessing each member in the class\n        for class_member_info in class_members:\n            # class_member_info is a namedtuple\n            assert isinstance(class_member_info, mikedoc.ClassMemberInfo)\n            # print the parsed docstring of each method in the class\n            if class_member_info.is_method:\n                # get the docstring\n                docstring = class_member_info.doc\n                # parse the docstring\n                data = mikedoc.parse_docstring(docstring)\n                # print the docstring\n                print(docstring)\n```\n\n## Parsing a docstring\n```python\nfrom mikedoc import parse_docstring\n\ndocstring = \"\"\"\nA multiline description\nfor a *function* that adds two numbers\n\n[params]\n- a: left-hand integer operand\n- b: right-hand integer operand\n\n[returns]\nSum of `a` and `b`\"\"\"\n\n# returns a dictionary\ndata = parse_docstring(docstring)\n\nprint(data)\n```\nThe code above would output this:\n```\n{'': 'A multiline description\\nfor a *function* that adds two numbers',\n 'param': {'a': 'left-hand integer operand',\n           'b': 'right-hand integer operand'}, \n 'return': 'Sum of `a` and `b`'}\n```\n\n\n# Demo\n**MikeDoc**'s API reference itself can serve as an explorable demo as well as those from other projects such as **Braq** and **Paradict**.\n\n| Project | API reference |\n| --- | --- |\n| [MikeDoc](#readme): Neat docstring format for building API references | [mikedoc/docs/api](https://github.com/pyrustic/mikedoc/blob/master/docs/api/README.md#mikedoc-api-reference) |\n| [Braq](https://github.com/pyrustic/braq): Customizable data format for config files, AI prompts, and more | [braq/docs/api](https://github.com/pyrustic/braq/blob/master/docs/api/README.md#braq-api-reference) |\n| [Paradict](https://github.com/pyrustic/paradict): Streamable multi-format serialization with schema | [paradict/docs/api](https://github.com/pyrustic/paradict/blob/master/docs/api/README.md#paradict-api-reference) |\n\n# Docstring format\nThe format can be summarized as follows:\n\n```python\ndef arbitrary_function(a, b):\n    \"\"\"\n    A description of the **function** that\n    might span multiple lines.\n    \n    [params]\n    Optional short text to introduce parameters.\n    - a: Short or long description that might\n    span multiple lines.\n    - b: Short or long description that might\n    span multiple lines.\n    \n    [returns]\n    This section describes the value to return.\n    \n    [yields]\n    This section describes the value to yield.\n    \n    [raises]\n    Optional short text to introduce\n    exceptions that might be raised.\n    - Exception: Short or long description that might\n    span multiple lines.\n    \"\"\"\n    ...\n```\n\nThe **MikeDoc** format uses [Braq](https://github.com/pyrustic/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.\n\n\u003e The docstring format allows reasonable use of [Markdown](https://en.wikipedia.org/wiki/Markdown) like emphasis and links. It is recommended to keep it simple.\n\n# Config file\nTo be able to build a reference API for an arbitrary Python project, a `mikedoc.kvf` [config file](https://github.com/pyrustic/kvf) should be placed at the root of the codebase directory. The file can be generated with the `init` command from the CLI.\n\nHere is the `mikedoc.kvf` config file placed at the root of **MikeDoc** itself:\n\n```\n# project name\nproject_name = 'MikeDoc'\n\n# project's website or README\nproject_url = '/README.md'\n\n# package directory (relative path)\npkg_dir = 'mikedoc'\n\n# API directory (relative path)\napi_dir = 'docs/api'\n```\n\nFor 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'`.\n\n\u003e Only the **slash character** is allowed as path separator in the config file.\n\u003e \n\u003e **For most cases**, the generated config file doesn't need to be edited.\n\n# Command-line interface\nThe `init` and `build` commands are all you need:\n\n```bash\n# cd in the project root dir\n$ cd /path/to/project/root\n\n# create the config file\n$ mikedoc init\nConfig file 'mikedoc.kvf' created !\n\n# build the api reference\n$ mikedoc build\nAPI reference built in 'docs/api' !\n```\n\n\u003e **For most cases**, the generated config file doesn't need to be edited.\n\n# Application programming interface\n\u003e Explore the [API Reference](/docs/api) !\n\n# API reference coverage\nAn API reference generated by this tool would comprehensively cover various elements of a **Python** codebase, including:\n- **Modules:** A module represents the main unit of a codebase.\n  - **Fields:** Variables and constants.\n  - **Functions**\n  - **Classes**\n    - **Regular classes**\n        - **Fields:** Also referred to as `class attributes`.\n        - **Properties:** `Getters`, `setters`, and `deleters`.\n        - **Methods**\n          - **Regular methods**\n          - **Static methods**\n          - **Class methods**\n    - **Enumerations**\n      - **Fields:** Also referred to as `enum members`.\n    - **Named Tuples**\n      - **Fields**\n\n# API reference rendering and navigation\n**MikeDoc** generates [Markdown](https://github.github.com/gfm/) files that can be rendered and browsed online on [GitHub](https://github.com/pyrustic/mikedoc) or explored offline with a Markdown reader. Markdown files are organized in directories that mirror the organization of the codebase.\n\n```\nproject\n    mikedoc.kvf\n    src\n        package  [1]\n            module1.py\n            sub_package\n                module2.py\n    docs\n        api  [2]\n            README.md  [3]\n            MIKEDOC\n            modules\n                package\n                    module1\n                        README.md  [4]\n                        class-MyClass1.md  [5]\n                        fields.md  [6]\n                        funcs.md  [7]\n                    sub_package\n                        module2\n                            README.md\n                            class-MyClass2.md\n                            fields.md\n                            funcs.md\n```\n\n- [1] - The package directory: `pkg_dir = 'src/package'`.\n- [2] - The API directory: `api_dir = 'docs/api'`.\n- [3] - Home page for the API reference.\n- [4] - Overview page for the `package.module1` module.\n- [5] - Page for documenting `MyClass1` exposed in `package.module1`.\n- [6] - Page for documenting public fields (variables and constants) exposed in `package.module1`.\n- [7] - Page for documenting public functions exposed in `package.module1`.\n\n\n\u003e **Navigation between pages** relies on **links** all **relative** to the **root directory**. These relative links are prefixed with a slash `/`.\n\n# Miscellaneous\nMiscellaneous stuff...\n## Underlined links on GitHub\nIn **Python**, underscores are very common in identifiers. When these identifiers are rendered as underlined links, it becomes hard to notice the underscores. \n\n\u003e To change the visibility of underlines on links that are adjacent to text, check the GitHub [accessibility settings](https://github.com/settings/accessibility).\n\n\n# Testing and contributing\nFeel 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](https://pyrustic.github.io/#contact).\n\n## Setup your development environment\nFollowing are instructions to setup your development environment\n\n```bash\n# create and activate a virtual environment\npython -m venv venv\nsource venv/bin/activate\n\n# clone the project then change into its directory\ngit clone https://github.com/pyrustic/mikedoc.git\ncd mikedoc\n\n# install the package locally (editable mode)\npip install -e .\n\n# run tests\npython -m unittest discover -f -s tests -t .\n\n# deactivate the virtual environment\ndeactivate\n```\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#readme\"\u003eBack to top\u003c/a\u003e\u003c/p\u003e\n\n# Installation\n**MikeDoc** is **cross-platform**. It is built on [Ubuntu](https://ubuntu.com/download/desktop) and should work on **Python 3.5** or **newer**.\n\n## Create and activate a virtual environment\n```bash\npython -m venv venv\nsource venv/bin/activate\n```\n\n## Install for the first time\n\n```bash\npip install mikedoc\n```\n\n## Upgrade the package\n```bash\npip install mikedoc --upgrade --upgrade-strategy eager\n```\n\n## Deactivate the virtual environment\n```bash\ndeactivate\n```\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#readme\"\u003eBack to top\u003c/a\u003e\u003c/p\u003e\n\n# About the author\nHello world, I'm Alex, a tech enthusiast ! Feel free to get in touch with [me](https://pyrustic.github.io/#contact) !\n\n\u003cbr\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\n[Back to top](#readme)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrustic%2Fmikedoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyrustic%2Fmikedoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrustic%2Fmikedoc/lists"}