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.
Project/Codebase | PLoC | Mosheh's Exec Time | |
---|---|---|---|
Mosheh | ~4k | 0.303s | |
scikit-learn | ~862k | ███████████ | 11.783s |
NumPy | ~204k | ████████████ | 12.205 |
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
, configuremosheh.json
andcreate
- 💼 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
Running Locally
Building Locally
Testing
Lint
Generate Self Document
Benchmarking
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.