Mosheh

Mosheh, automatic and elegant documentation of Python code with MkDocs.

Inspirated by cargodoc - a Rust tool for code documenting - and using MkDocs + Material MkDocs, Mosheh is an easy, fast, plug-and-play tool which saves time while automating the process of documenting the source code of a Python codebase.

PLoC: Python Lines of Code

Specs: Mint 21.3 | Aspire A515-54 | Intel i7-10510U (8) @ 4.900GHz | RAM 19817MiB

• 🏎 Fast: Documented NumPy (200k+ Python LoC) in just 12.2 seconds
• 🙂 Simple: No complex logic behind the scenes — easy to understand and trust
• 👌 Easy to Use: No advanced knowledge required — document any Python codebase effortlessly
• 🔌 Plug and Play: No need to modify your codebase — just install Mosheh, init, configure mosheh.json and create
• 💼 Professional: Generates MkDocs Material-based documentation — a clean, responsive, and professional website by default
• 🧑‍💻 Modern: Designed for modern Python — fully type-hint-aware and built using the latest Python best practices
• 📈 Scalable: Handles small scripts to massive codebases without performance issues
• ➰ Flexible: Works with any Python structure — does not enforce docstring formats or architectural patterns
• 🔓 Open Source: Free to use, fully open-source under the MIT license, and built with community in mind
• 🔗 Integrable: Easy to embed into CI/CD pipelines or project scaffolds for automatic documentation generation

This is not an alternative to MkDocs, but a complement based on it, since Mosheh lists all files you points to, saves every single notorious definition statement on each file iterated, all using Python ast native module for handling the AST and then generating a modern documentation respecting the dirs and files hierarchy.

At the moment, Mosheh documents only Python files (.py, .pyi), where the stuff documented for each file is shown below:

• Imports ast.Import | ast.ImportFrom

  • Type Native | TrdParty | Local
  • Path (e.g. math.sqrt)
  • Code

• Constants ast.Assign | ast.AnnAssign

  • Name (token name)
  • Typing Annotation (datatype)
  • Value (literal or call)
  • Code

• Classes ast.ClassDef

  • Description (docstring)
  • Name (class name)
  • Parents (inheritance)
  • Methods Defined (nums and names)
  • Code

• Funcs ast.FunctionDef | ast.AsyncFunctionDef

  • Description (docstring)
  • Name (func name)
  • Type Func | Method | Generator | Coroutine
  • Parameters (name, type, default)
  • Return Type (datatype)
  • Raises (exception throw)
  • Code

• Assertions ast.Assert

  • Test (assertion by itself)
  • Message (opt. message in fail case)
  • Code

Stack

Contributing

Before getting access to the To-Do List, Coding Style or even forking the project, we strongly recommend reading Mosheh's Guidelines

Arch

Mosheh's architecture can be interpreted in two ways: the directory structure and the interaction of the elements that make it up. A considerable part of a project is - or at least should be - that elements that are dispensable for its functionality are in fact dispensable, such as the existence of automated tests; they are important so that any existing quality process is kept to a minimum acceptable level, but if all the tests are deleted, the tool still works.

Here it is no different, a considerable part of Mosheh is, in fact, completely dispensable; follow below the structure of directories and relevant files that are part of this project:

.
├── mosheh/                     # Mosheh's source-code
│   ├── commands/*              # Logics for each command
│   ├── handlers/*              # Codebase handlers for each file
│   ├── doc/*                   # Documentation build logics
│   ├── types/                  # Custom data types
│   │   ├── basic.py            # Basic types (e.g. "type Token = str")
│   │   ├── contracts.py        # Contracts to ensure correct typing
│   │   ├── enums.py            # Enums for standardizing assignments
│   │   └── jsoncfg.py          # JSON for structuring commands config
│   ├── codebase.py             # Codebase reading logic
│   ├── constants.py            # Constants to be evaluated
│   ├── main.py                 # Entrypoint
│   └── utils.py                # Utilities
│
├── tests/                      # Template dir for testing
│   ├── DOC                     # Doc output dir
│   ├── PROJECT                 # Template project dir
│   └── unittest                # Automated tests
│
├── documentation/              # Mosheh's documentation dir
│   ├── docs/                   # Dir containing .md files and assets
│   ├── mkdocs.yml              # MkDocs's config file
│   └── mosheh.json             # Mosheh's exec config file
│
├── pyproject.toml              # Mosheh's config file for almost everything
├── uv.lock                     # uv's lockfile for dealing with dependencies
├── .python-version             # Default Python's version to use
│
├── .github/                    # Workflows and social stuff
│
├── LICENSE                     # Legal stuff, A.K.A donut sue me
│
└── .gitignore                  # Git "exclude" file

It is to be expected that if the tests/ directory is deleted, Mosheh's core will not be altered in any way, so much so that when a tool is downloaded via pip or similar, the tool is not accompanied by tests, licenses, development configuration files or workflows. So, to help you understand how the mosheh/ directory works, here's how the functional elements interact with each other:

Usage

After installing Mosheh as a development dependency, create the documentation folder if not exists and run mosheh init [--path .]; this will result in a mosheh.json config file just as below:

{
  "documentation": {
    "projectName": "Mosheh",
    "repoName": "mosheh",
    "repoUrl": "https://github.com/lucasgoncsilva/mosheh",
    "editUri": "blob/main/documentation/docs",
    "siteUrl": "https://lucasgoncsilva.github.io/mosheh/",
    "logoPath": "./path/to/logo.svg",
    "readmePath": "./path/to/README.md",
    "codebaseNavPath": "Codebase"
  },
  "io": {
    "rootDir": "./app/",
    "outputDir": "./path/to/output/"
  }
}

After making sure the data on that JSON reflects the desired (more about this file at the official documentation), running mosheh create [--json .] results in a documentation following the default MkDocs structure with Material MkDocs as theme, with the codebase documented over "Codebase" named-section.

Development

Installing Dependencies

# Automatically handles everything with .venv
uv sync

Running Locally

# For running using uv and dealing with Mosheh as a module
uv run mosheh -h

Building Locally

# Build pip-like file
uv build

Testing

# Run all the testing workflow
uv run task test

Lint

# Run all the linting workflow
uv run task lint

Generate Self Document

# Generate Mosheh's Codebase Documentation
uv run task makedoc

Benchmarking

# Running benchmark with Memray and Scalene
uv run task benchmark

License

This project is under MIT License. A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.