Package: lazydocs
lazydocsGenerate markdown API documentation for Google-style Python docstring.Getting Started•Features•Documentation•Support•Contribution•ChangelogLazydocs makes it easy to generate beautiful markdown documentation for your Python API (see thisexample). It provides asimple command-line interfaceas well as aPython APIto get full-fledged API documentation within seconds based on all of theGoogle-style docstringsin your code. This markdown documentation can be pushed to Github or integrated into your MkDocs site.Highlights⏱  Simple CLI to generate markdown docs in seconds.📋  SupportsGoogle-style Python Docstrings.📚  Compatible with Github Markdown and MkDocs.Getting StartedInstallationRequirements: Python 3.6+.pipinstalllazydocsUsageTo generate Markdown-based API documentation for your Python project, simply execute:lazydocspath/to/your/packageThe path can be either a python package (folder) or a specific script. You can also specify one or multiple module-, class- or function-imports:lazydocsmy_package.AwesomeClassWith the default configuration, the Markdown documentation will be generated inside the./docsfolder in your working directory. You can find additional configuration options in thedocumentation section.Support & FeedbackThis project is maintained byBenjamin Räthlein,Lukas Masuch, andJan Kalkan. Please understand that we won't be able to provide individual support via email. We also believe that help is much more valuable if it's shared publicly so that more people can benefit from it.TypeChannel🚨Bug Reports🎁Feature Requests👩‍💻Usage Questions🗯General Discussion❓Other RequestsFeaturesSource Code Linking•API Overview•MKDocs Integration•Docstyle Validation•Print to ConsoleSource Code LinkingLazydocs is capable to insert a badge on the right side of every module, class, method or function with a link the correct source-code file and line number. The default configuration will create relative paths to navigate within the Github Repo. This is useful if the documentation is hosted within the same repository as the source-code. If, the documentation is hosted outside of the Github repository, it is recommended to set thesrc-base-url:lazydocs--src-base-url="https://github.com/example/my-project/blob/main/"my_packageThesrc-base-urlis used as a prefix for all source-code linkings in the documentation.API OverviewAn API overview might be very useful in case your project has a large number modules, classes and functions. You can specify anoverview-filewith the lazydocs command to activate the generation of an API overview:lazydocs--overview-file="README.md"my_packageThe API overview will be written as markdown to the specified file with separated lists for all modules, classes, and functions of your project:MkDocs IntegrationThe markdown documentation generated by lazydocs can be easily integrated into yourmkdocsdocumentation site:Generate the markdown documentation into a subfolder (e.g.api-docs) inside your mkdocs documentation. We recommend to use theoverview-fileoption and set the source-code URL viasrc-base-url, otherwise the source-code linking would not work:lazydocs\--output_path="./docs/api-docs"\--overview-file="README.md"\--src-base-url="https://github.com/example/my-project/blob/main/"\my_packageInstall and apply theawesome-pages mkdocs plugin. This enables mkdocs to automatically discover and include all markdown files. The alternative would be to manually include all generated markdown files in the navigation section of themkdocs.yaml. In order to use the awesome-pages plugin you need to 1) install the plugin via pip 2) Include it in the plugin sectionmkdocs.yamland remove the navigation section (needs to be handled with.pagesfiles).If you used theoverview-fileoption, a.pagesfile will be automatically created. You can also manually create the.pagesfile within the api-docs subfolder (e.g.api-docs) with the following content:title:API Referencenav:-Overview:README.md-...Once you run or deploy your mkdocs documentation, you will see the API Reference section with all of your API markdown documentation.Docstyle ValidationLazydocs can only parse valid Google-style docstring. To prevent the generation of invalid markdown documentation, you can use thevalidateflag:layzdocs--validatemy_packageThis will runpydocstyleon your docstring and cancel the generation if an issue is found.Print to ConsoleTo get the markdown documentation as console output instead of the file generation, specifystdoutas theoutput-path:layzdocs--output-path=stdoutmy_packageDocumentationCLI Interfacelaydocs[OPTIONS]PATHS...Arguments:PATHS...: Selected paths or imports for markdown generation.  [required]Options:--output-path TEXT: The output path for the creation of the markdown files. Set this tostdoutto print all markdown to stdout.  [default: ./docs/]--src-base-url TEXT: The base repo link used as prefix for all source links. Should also include the branch name.--overview-file TEXT: Filename of overview file. If not provided, no API overview file will be generated.--remove-package-prefix / --no-remove-package-prefix: IfTrue, the package prefix will be removed from all functions and methods.  [default: True]--ignored-modules TEXT: A list of modules that should be ignored.  [default: ]--watermark / --no-watermark: IfTrue, add a watermark with a timestamp to bottom of the markdown files.  [default: True]--validate / --no-validate: IfTrue, validate the docstrings via pydocstyle. Requires pydocstyle to be installed.  [default: False]--install-completion: Install completion for the current shell.--show-completion: Show completion for the current shell, to copy it or customize the installation.--help: Show this message and exit.Programmatic APILazydocs can also be used and integrated via itsPython API. For example, to generate markdown for an arbitrary Python import or object:fromlazydocsimportMarkdownGeneratorgenerator=MarkdownGenerator()# Select a module (e.g. my_module) to generate markdown documentationmarkdown_docs=generator.import2md(my_module)To programmatically generate all markdown documentation files you can usegenerate_docs:fromlazydocsimportgenerate_docs# The parameters of this function correspond to the CLI optionsgenerate_docs(["my_module"],output_path="./docs")The full Python API documentation can be foundhere(generated via lazydocs).ContributionPull requests are encouraged and always welcome. Read ourcontribution guidelinesand check outhelp-wantedissues.Submit Github issues for anyfeature request and enhancement,bugs, ordocumentationproblems.By participating in this project, you agree to abide by itsCode of Conduct.Thedevelopment sectionbelow contains information on how to build and test the project after you have implemented some changes.DevelopmentRequirements:DockerandActare required to be installed on your machine to execute the build process.To simplify the process of building this project from scratch, we provide build-scripts - based onuniversal-build- that run all necessary steps (build, check, test, and release) within a containerized environment. To build and test your changes, execute the following command in the project root folder:act-b-jbuildRefer to ourcontribution guidesfor more detailed information on our build scripts and development process.LicensedMIT. Created and maintained with ❤️  by developers from Berlin.