Skip to main content

Python docstring-based documentation generator for lazy perfectionists.

Project description

🙌 Handsdown - Python documentation generator

PyPI PyPI - Python Version PyPI - Format PyPI - Status Travis (.org) Codecov

Python docstring-based documentation generator for lazy perfectionists.

🔬 Features

  • 👓 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, open docs right on GitHub or deploy it on GitHub Pages!
  • 📚 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 Modules
  • 🔎 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?

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, and even if you do not
  • are proud of your project and not afraid to show it
  • love Open Source

And probably do not if you:

  • plan to build html pages locally (Look at
  • pydocmd, they are doing a great job!)
  • not very into docstrings and type annotations
  • like to abstract a documentation away from the way things really are
  • use Pandas docstrings as they are not supported yet

🐏 Examples

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.

🎉 Usage

💻 From command line

Just go to your favorite project that has lots of docstrings but missing auto-generated docs, install dependencies to avoid import errors 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

# okay, what about Django?
# you need to set `DJANGO_SETTINGS_MODULE`
# and exclude migrations folders as they usually are not very interesting
export DJANGO_SETTINGS_MODULE="settings" # use your path to settings
handsdown --exclude */migrations

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

📝 As a GitHub Pages manager

handsdown comes with a 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

🧩 As a module

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

🐶 Installation

Install using pip from PyPI

pip install handsdown

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

pip install git+https://github.com/vemel/handsdown.git

🔧 Development

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

handsdown-0.2.1.tar.gz (30.4 kB view hashes)

Uploaded Source

Built Distribution

handsdown-0.2.1-py2.py3-none-any.whl (41.7 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page