GitLocker: The Coding Marketplace

Description:

handsdown 2.1.0

🙌 Handsdown - Python documentation generator

Python docstring-based documentation generator for lazy perfectionists.

🙌 Handsdown - Python documentation generator

Features
Do you need handsdown?
Examples
Usage

💻 From command line
🚀 Use a new Material design
📦 As a Docker image
📝 As a GitHub Pages manager
🐏 Deploy on Read the Docs
📋 Build static HTML
🧩 As a module
⌨️ CLI arguments

Installation
Development
Changelog

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?
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

And probably do not if you:

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

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 Docker image

Install Docker
Pull latest handsdown version and tag it

docker pull ghcr.io/vemel/handsdown/handsdown:latest
docker tag ghcr.io/vemel/handsdown/handsdown:latest handsdown

Generate docs for ProjectName in current directory

# for Python 3 project
docker run -v `pwd`:/app handsdown -n ProjectName

# for Python 2 project
PYTHON_VER=2 docker run -v `pwd`:/app handsdown -n ProjectName

# generate documentation for deployment
docker run -v `pwd`:/app handsdown --external `git config --get remote.origin.url` -n ProjectName --create-configs

📝 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

-i / --input-path
Path to project root folder

-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>

-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

-h
Show help

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 poetry
Run poetry install
Use black formatter in your IDE

Changelog
Changelog can be found in Releases