# ๐ Handsdown - Python documentation generator
Project description
๐ 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
orFlask
applications, and even if you do not - are proud of your project and are 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!
๐ GitHub Pages
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
๐งฉ 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
pip install handsdown
๐ง Development
- Install pipenv
- Run
pipenv install -d
- Use
black
formatter in your IDE
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for handsdown-0.1.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8fd69385c9df76ecce6495097b5e97b076c64cb24663da18449c6ffbf2863b95 |
|
MD5 | 7c8c52b9c60f4108a4ea8d8f56514f43 |
|
BLAKE2b-256 | 8c81cd7b443efa3d4b088ee9a356e5f7d90cae1a1f2350b78e943ec788978b71 |