Research
Security News
Malicious npm Package Targets Solana Developers and Hijacks Funds
A malicious npm package targets Solana developers, rerouting funds in 2% of transactions to a hardcoded address.
Python docstring-based documentation generator for lazy perfectionists.
__future__
!README.md
in submodules to one placemodule.import.String
to docs.You definitely do if you:
Django
or Flask
applicationsAnd probably do not if you:
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!
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
handsdown
version and tag itdocker pull ghcr.io/vemel/handsdown/handsdown:latest
docker tag ghcr.io/vemel/handsdown/handsdown:latest handsdown
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
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
--external
flag as shown above, do not use --output
flag, only docs
folder is supported by GitHub Pages
main
branch.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
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
--external
flag as shown above, do not use --output
flag, only docs
folder is supported by Read the Docs
main
branch.All set! You can change .readthedocs.yml
and mkdocs.yml
to add your own touch.
# 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
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
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 |
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
poetry install
black
formatter in your IDEChangelog can be found in Releases
FAQs
Python docstring-based documentation generator for lazy perfectionists.
We found that handsdown demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A malicious npm package targets Solana developers, rerouting funds in 2% of transactions to a hardcoded address.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.