handsdown 0.2.1

Python docstring-based documentation generator for lazy perfectionists.

🙌 Handsdown - Python documentation generator

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