🙌 Handsdown-fork

A fork of handsdown, the python docstring-based documentation generator for lazy perfectionists.

Huge thanks to https://github.com/vemel/handsdown for all of the groundwork!

• 🙌 Handsdown-fork
  • Features
  • Do you need handsdown-fork?
  • Examples
  • Usage
    • 💻 From command line
    • 🚀 Use a new Material design
    • 📝 As a GitHub Pages manager
    • 🐏 Deploy on Read the Docs
    • 📋 Build static HTML
    • 🧩 As a module
    • ⌨️ CLI arguments
  • Project Documentation
  • Installation
  • Language information
  • Working with the repo
  • Community Files
    • Licence
    • Code of Conduct
    • Contributing
    • Security
    • Support

Features

• Material design support!
• PEP 257, Google, Sphinx and reStructuredText docstrings support. All of them are converted to a valid Markdown.
• Works with Django and Flask apps
• Can be used locally, or right on GitHub or even deployed on GitHub Pages and Read the Docs!
• Signatures for every class, function, property and method.
• Support for type annotations. Even for the ones from the __future__!
• Nice list of all modules in Index
• Gather all scattered README.md in submodules to one place
• Find related source code from every doc section.
• Make links by just adding module.import.String to docs.
• Do you use type annotations? Well, you get auto-discovery of related modules for free!

Do you need handsdown-fork?

You definitely do if you:

• prefer to automate documentation builds
• work with a team and plan to simplify knowledge sharing
• want to show your project without navigating through a source code
• build Django or Flask applications
• are proud of your project and not afraid to show it
• love Open Source

Examples

• All documentation in this project
• Main with generated output
• RST docstrings with generated output
• Google docstrings with generated output
• PEP 257 docstrings with generated output
• Sphinx docstrings with generated output
• Type annotations with generated output
• Comment-style type annotations with generated output

Usage

💻 From command line

Just go to your favorite project that has lots of docstrings but missing auto-generated docs and let handsdown do the thing.

cd ~/my/project

# build documentation *.md* files in docs/* directory
handsdown

# or provide custom output directory: output_dir/*
handsdown -o output_dir

# generate docs only for my_module, but exclude migrations
handsdown my_module --exclude my_module/migrations

# generate documentation for deployment
handsdown --external `git config --get remote.origin.url` -n ProjectName --branch main --create-configs

Navigate to docs/README.md to check your new documentation!

🚀 Use a new Material design

• Add mkdocs and mkdocs-material to your dev dependencies or just install them

# generate MarkDown documentation in docsmd folder
handsdown --external `git config --get remote.origin.url` -o docsmd -n <project_name> --theme=material --create-configs

# generate html files to docs folder
python -m mkdocs build

📝 As a GitHub Pages manager

With --external CLI flag, handsdown generates all required configuration for GitHub Pages, so you just need to setup your GitHub repository.

# Generate documentation that points to main branch
# do not use custom output location, as `GitHub Pages`
# works only with `docs` directory
handsdown --external `git config --get remote.origin.url` --create-configs

# or specify GitHub url directly
handsdown --external https://github.com/<user>/<project> --create-configs

• Generate documentation with --external flag as shown above, do not use --output flag, only docs folder is supported by GitHub Pages
• Commit and push all changes a to main branch.
• Set your GitHub project Settings > GitHub Pages > Source to main branch /docs folder

All set! You can change docs/_config.yml to add your own touch.

With --external flag links to your source are absolute and point to your GitHub repo. If you still want to have relative links to source, e.g. for using docs locally, generate docs to another folder

# `docs_local` folder will be created in your project root
# you probably want to add it to .gitignore
handsdown -o docs_local

🐏 Deploy on Read the Docs

With --external CLI flag, handsdown generates all required configuration for Read the Docs, so you just need to to add your GitHub repository to Read the Docs.

# Generate documentation that points to main branch
# do not use custom output location, as `GitHub Pages`
# works only with `docs` directory
handsdown --external `git config --get remote.origin.url` --create-configs

# or specify GitHub url directly
handsdown --external https://github.com/<user>/<project>/ --create-configs

• Generate documentation with --external flag as shown above, do not use --output flag, only docs folder is supported by Read the Docs
• Commit and push all changes a to main branch.
• Add your repository on Read the Docs

All set! You can change .readthedocs.yml and mkdocs.yml to add your own touch.

📋 Build static HTML

# Generate documentation that points to main branch
# with source links pointing to your repository
# this command also creates `mkdocs.yml`
handsdown --external `git config --get remote.origin.url` --create-configs

# Run mkdocs to build HTML
python -m mkdocs build

🧩 As a module

from handsdown.generator import Generator
from handsdown.utils.path_finder import PathFinder

# this is our project root directory
repo_path = Path.cwd()

# this little tool works like `pathlib.Path.glob` with some extra magic
# but in this case `repo_path.glob("**/*.py")` would do as well
path_finder = PathFinder(repo_path, "**/*.py")

# no docs for tests and build
path_finder.exclude("tests/*", "build/*")

# initialize generator
handsdown = Generator(
    input_path=repo_path,
    output_path=repo_path / 'output',
    source_paths=path_finder.glob("**/*.py")
)

# generate all docs at once
handsdown.generate_docs()

# or generate just for one doc
handsdown.generate_doc(repo_path / 'my_module' / 'source.py')

# generate index.md file
handsdown.generate_index()

# and generate GitHub Pages and Read the Docs config files
handsdown.generate_configs()

# navigate to `output` dir and check results

⌨️ CLI arguments

handsdown [-h] [--exclude [EXCLUDE ...]] [-i INPUT_PATH] [-f [FILES ...]]
  [-o OUTPUT_PATH] [--external REPO_URL] [--source-code-path REPO_PATH]
  [--branch BRANCH] [--toc-depth TOC_DEPTH] [--cleanup] [-n PROJECT_NAME]
  [-e ENCODING] [--panic] [-d] [-q] [-V]
  [include ...]

Argument	Description	Default
include	Path expressions to include source files
--exclude	Path expressions to exclude source files	'build/*' 'tests/*' 'test/*' '*/__pycache__/*' '.*/*'
-i / --input-path	Path to project root folder	<cwd>
-f / --files	List of source files to use for generation. If empty - all are used.
-o / --output-path	Path to output folder	<cwd>/docs
--external	Build docs and config for external hosting, GitHub Pages or Read the Docs. Provide the project GitHub .../blob/main/ URL here.
--source-code-path	Path to source code in the project. Overrides --branch CLI argument
--branch	Main branch name	main
--toc-depth	Maximum depth of child modules ToC	3
--cleanup	Remove orphaned auto-generated docs
-n / --name	Project name	<cwd>.name
-e / --encoding	Input and output file encoding	utf-8
--panic	Panic and die on import error
--debug	Show debug messages
--quiet	Hide log output
--create-configs	Create config files for deployment to RtD and GitHub Pages
-t / --theme	Output mkdocs theme: readthedocs or material	readthedocs
-h	Show help

Project Documentation

A high-level overview of how the documentation is organized organized will help you know where to look for certain things:

• The Technical Reference documents APIs and other aspects of the machinery. This documentation describes how to use the classes and functions at a lower level and assume that you have a good high-level understanding of the software. Note this is generated with handsdown-fork

Installation

Install using pip from PyPI

pip install handsdown-fork

or directly from GitHub if you cannot wait to test new features

pip install git+https://github.com/FHPythonUtils/handsdown-fork.git

Language information

Using python 3.9, to 3.14

Working with the repo

Clone, the repo with

git clone https://github.com/FHPythonUtils/handsdown-fork

Format

uv run ruff format

Linting

uv run ruff check
uv run python3 -m basedpyright -p .

Testing

uv run python3 -m pytest

Alternatively use tox to run tests over a range of python versions

uvx tox

Documentation

uv run handsdown

Community Files

Licence

MIT License Copyright (c) FredHappyface Copyright (c) 2019 Vlad Emelianov (See the LICENSE for more information.)

Code of Conduct

Online communities include people from many backgrounds. The Project contributors are committed to providing a friendly, safe and welcoming environment for all. Please see the Code of Conduct for more information.

Contributing

Contributions are welcome, please see the Contributing Guidelines for more information.

Security

Thank you for improving the security of the project, please see the Security Policy for more information.

Support

Thank you for using this project, I hope it is of use to you. Please be aware that those involved with the project often do so for fun along with other commitments (such as work, family, etc). Please see the Support Policy for more information.