Material for nbdev¤
Source Code: https://github.com/airtai/nbdev-mkdocs
The key features are:
- Material style documentation: Effortlessly create material style documentation for your nbdev projects with Material for MkDocs, a theme that provides a sleek and modern design for your documentation.
- Auto generate docstrings: Instantly generate docstrings for your Python code using docstring-gen library, a tool that automatically generates docstrings for your functions and classes using Codex.
- Create stunning social media share images: Boost your project’s visibility by creating striking social share images using DALL-E.
- Customizability: Add guides, release notes, customise the navigation menu and configure the Material for MkDocs easily to suit your project needs. With this documentation tool, you have more control over the look and feel of your documentation, allowing you to create a unique and personalized experience for your users.
Here’s a quick comparison of Quarto and Material for nbdev development workflows:
|Quarto workflow||Material for nbdev workflow|
The following quick start guide will walk you through installing and configuring nbdev-mkdocs for an existing nbdev project. It also assumes you’ve already initialized your project with nbdev and installed all of the required libraries.
For detailed installation instructions and configuration options, please see the User Guide.
nbdev-mkdocs is published as a Python package and can be installed with pip:
pip install nbdev-mkdocs
nbdev-mkdocs must be installed in the same Python
environment as nbdev.
If the installation was successful, you should now have the nbdev-mkdocs installed on your system. Run the below command from the terminal to see the full list of available commands:
Usage: nbdev_mkdocs [OPTIONS] COMMAND [ARGS]... ╭─ Options ────────────────────────────────────────────────────────────────────╮ │ --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. │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │ delete-pre-release-docs Deletes deployed pre-release documentation │ │ versions. │ │ docs Prepares files in **mkdocs/docs** and then runs │ │ **mkdocs build** command on them │ │ docstring Command for adding docstrings to classes and │ │ methods that don't have one using docstring-gen │ │ library. │ │ new Creates files in **mkdocs** subdirectory needed for │ │ other **nbdev_mkdocs** subcommands │ │ prepare Runs tests and prepares files in **mkdocs/docs** │ │ and then runs **mkdocs build** command on them │ │ preview Prepares files in **mkdocs/docs** and then runs │ │ **mkdocs serve** command on them │ │ social-image Command for generating a custom social share image. │ ╰──────────────────────────────────────────────────────────────────────────────╯
After installing nbdev-mkdocs, bootstrap your project documentation by executing the following command from the project’s root directory:
Using information from the project’s settings.ini file, the above command creates files and directories required to build the documentation and saves it in the mkdocs subdirectory.
Note: You should only run the nbdev_mkdocs new command once for the project to initialise the files required for building Material for MkDocs documentation.
nbdev_mkdocs lets you preview your changes as you write your documentation. Execute the following command from the project root directory to start a local server, and preview your documentation:
Note: If you haven’t already installed your library locally, run
pip install -e '.[dev]' command before running the
nbdev_mkdocs prepare command.
We recommend running the
nbdev_mkdocs prepare command in the terminal
before committing to Git, which exports the library, tests and cleans
notebooks, and generates the README file if necessary.
Finally, double-check your settings.ini file to ensure that it has all of the correct information. Then commit and push your additions to GitHub:
git commit -am'Commit Message' git push
Copyright © 2022 onwards airt technologies ltd, Inc.
This project is licensed under the terms of the Apache License 2.0