Python docstring-based documentation generator for lazy perfectionists.

• 🙌 Handsdown - Python documentation generator
  • 🔬 Features
  • 🐏 Examples
  • 🎉 Usage
    • 💻 From command line
    • 📝 GitHub Pages
    • 🧩 As a module
  • 🐶 Installation
  • 🔧 Development

• 👓 PEP 257, Google and reStructuredText docstrings support. All of them are converted to a valid markdown.
• 🐍 Works with Django and Flask apps
• 🐈 Github-friendly. Use your local markdown viewer or open docs right on Github
• 📚 Signatures for every class, function and method.
• 🚀 Support for type annotations. Even for the ones from the __future__!
• 📦 Nice list of all modules in Modules
• 🔎 Gather all scattered README.md in submodules to one place
• 🚧 Links to source code from every doc section.
• #️⃣ Make links by just adding module.import.String to docs.
• 💕 Do you love type annotations? Well, you get auto-discovery of related modules for free!

handsdown built a nice documentation for itself to show it's abilities. Check how it works under the hood or discover examples with different docstrings format.

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

# output buolt MD files to docs/*
handsdown

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

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

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

handsdown comes with built-in support for GitHub Pages, although some setup is required. By default documentation uses relative links to source files, so for GitHub Pages we need absolute URLs to a GitHub repositore for find in source code links to work.

Now let's generate GitHub Pages-friendly documentation

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

# or specify GitHub url directly
handsdown --gh-pages https://github.com/<user>/<project>/blob/master/

Commit your changes and enable GitHub Pages by setting your project Settings > GitHub Pages > Source to master branch /docs folder

That's it, you are good to go! Add plugins to docs/_config.yml or change theme to add your own touch.

If you still want to have relative links to source, e.g. for using docs locally, generate docs to another folder

handsdown -o docs_local # `docs_local` folder will be created in your project root

from handsdown import Generator, 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')

# and generate index.md file
handsdown.generate_index()

# navigate to `output` dir and check results

Install using pip

pip install handsdown

• Install pipenv
• Run pipenv install -d
• Use black formatter in your IDE