Package: handsdown
🙌 Handsdown - Python documentation generatorPython docstring-based documentation generator for lazy perfectionists.🙌 Handsdown - Python documentation generatorFeaturesDo you need handsdown?ExamplesUsage💻 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 argumentsInstallationDevelopmentChangelogFeaturesMaterial designsupport!PEP 257,Google,SphinxandreStructuredTextdocstrings support. All of them are converted to a valid Markdown.Works withDjangoandFlaskappsCan be used locally, orright on GitHubor even deployed onGitHub PagesandRead 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 inIndexGather all scatteredREADME.mdin submodules to one placeFind related source code from every doc section.Make links by just addingmodule.import.Stringto docs.Do you use type annotations? Well, you get auto-discovery of related modules for free!Do you need handsdown?You definitelydoif you:prefer to automate documentation buildswork with a team and plan to simplify knowledge sharingwant to show your project without navigating through a source codebuildDjangoorFlaskapplicationsare proud of your project and not afraid to show itlove Open SourceAnd probablydo notif you:not very into docstrings and type annotationslike to abstract a documentation away from the way things really areusePandas docstringsas they are not supported yetExamplesAll documentationin this projectMainwithgenerated outputRST docstringswithgenerated outputGoogle docstringswithgenerated outputPEP 257 docstringswithgenerated outputSphinx docstringswithgenerated outputType annotationswithgenerated outputComment-style type annotationswithgenerated outputUsage💻 From command lineJust go to your favorite project that has lots of docstrings but missing
auto-generated docs and lethandsdowndo the thing.cd~/my/project# build documentation *.md* files in docs/* directoryhandsdown# or provide custom output directory: output_dir/*handsdown-ooutput_dir# generate docs only for my_module, but exclude migrationshandsdownmy_module--excludemy_module/migrations# generate documentation for deploymenthandsdown--external`gitconfig--getremote.origin.url`-nProjectName--branchmain--create-configsNavigate todocs/README.mdto check your new documentation!🚀 Use a new Material designAddmkdocsandmkdocs-materialto your dev dependencies or just install them# generate MarkDown documentation in docsmd folderhandsdown--external`gitconfig--getremote.origin.url`-odocsmd-n<project_name>--theme=material--create-configs# generate html files to docs folderpython-mmkdocsbuild📦 As a Docker imageInstallDockerPull latesthandsdownversion and tag itdockerpullghcr.io/vemel/handsdown/handsdown:latest
dockertagghcr.io/vemel/handsdown/handsdown:latesthandsdownGenerate docs forProjectNamein current directory# for Python 3 projectdockerrun-v`pwd`:/apphandsdown-nProjectName# for Python 2 projectPYTHON_VER=2dockerrun-v`pwd`:/apphandsdown-nProjectName# generate documentation for deploymentdockerrun-v`pwd`:/apphandsdown--external`gitconfig--getremote.origin.url`-nProjectName--create-configs📝 As a GitHub Pages managerWith--externalCLI flag,handsdowngenerates all required configuration
forGitHub 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` directoryhandsdown--external`gitconfig--getremote.origin.url`--create-configs# or specify GitHub url directlyhandsdown--externalhttps://github.com/<user>/<project>--create-configsGenerate documentation with--externalflag as shown above, do not use--outputflag, onlydocsfolder is supported byGitHub PagesCommit and push all changes a tomainbranch.Set your GitHub projectSettings>GitHub Pages>Sourcetomain branch /docs folderAll set! You can changedocs/_config.ymlto add your own touch.With--externalflag 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 .gitignorehandsdown-odocs_local🐏 Deploy on Read the DocsWith--externalCLI flag,handsdowngenerates all required configuration
forRead the Docs, so you just need to to add your
GitHub repository toRead the Docs.# Generate documentation that points to main branch# do not use custom output location, as `GitHub Pages`# works only with `docs` directoryhandsdown--external`gitconfig--getremote.origin.url`--create-configs# or specify GitHub url directlyhandsdown--externalhttps://github.com/<user>/<project>/--create-configsGenerate documentation with--externalflag as shown above, do not use--outputflag, onlydocsfolder is supported byRead the DocsCommit and push all changes a tomainbranch.Add your repository onRead the DocsAll set! You can change.readthedocs.ymlandmkdocs.ymlto 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`gitconfig--getremote.origin.url`--create-configs# Run mkdocs to build HTMLpython-mmkdocsbuild🧩 As a modulefromhandsdown.generatorimportGeneratorfromhandsdown.utils.path_finderimportPathFinder# this is our project root directoryrepo_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 wellpath_finder=PathFinder(repo_path,"**/*.py")# no docs for tests and buildpath_finder.exclude("tests/*","build/*")# initialize generatorhandsdown=Generator(input_path=repo_path,output_path=repo_path/'output',source_paths=path_finder.glob("**/*.py"))# generate all docs at oncehandsdown.generate_docs()# or generate just for one dochandsdown.generate_doc(repo_path/'my_module'/'source.py')# generate index.md filehandsdown.generate_index()# and generate GitHub Pages and Read the Docs config fileshandsdown.generate_configs()# navigate to `output` dir and check results⌨️ CLI argumentshandsdown[-h][--exclude[EXCLUDE...]][-iINPUT_PATH][-f[FILES...]][-oOUTPUT_PATH][--externalREPO_URL][--source-code-pathREPO_PATH][--branchBRANCH][--toc-depthTOC_DEPTH][--cleanup][-nPROJECT_NAME][-eENCODING][--panic][-d][-q][-V][include...]ArgumentDescriptionDefaultincludePath expressions to include source files--excludePath expressions to exclude source files-i/--input-pathPath to project root folder-f/--filesList of source files to use for generation. If empty - all are used.-o/--output-pathPath to output folder<cwd>/docs--externalBuild docs and config for external hosting, GitHub Pages or Read the Docs. Provide the project GitHub .../blob/main/ URL here.--source-code-pathPath to source code in the project. Overrides--branchCLI argument--branchMain branch namemain--toc-depthMaximum depth of child modules ToC3--cleanupRemove orphaned auto-generated docs-n/--nameProject name<cwd>-e/--encodingInput and output file encodingutf-8--panicPanic and die on import error--debugShow debug messages--quietHide log output--create-configsCreate config files for deployment to RtD and GitHub Pages-t/--themeOutput mkdocs themereadthedocs-hShow helpInstallationInstall usingpipfrom PyPIpipinstallhandsdownor directly from GitHub if you cannot wait to test new featurespipinstallgit+https://github.com/vemel/handsdown.gitDevelopmentInstallpoetryRunpoetry installUseblackformatter in your IDEChangelogChangelog can be found inReleases