Package: nbdev-mkdocs
Material for nbdevDocumentation:https://nbdev-mkdocs.airt.aiSource Code:https://github.com/airtai/nbdev-mkdocsGetting StartedMaterial for nbdevis anbdevextension
that allows you to useMaterial
for MkDocsto generate documentation for nbdev projects.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 usingdocstring-genlibrary, 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.WorkflowHere’s a quick comparison of Quarto and Material for nbdev development
workflows:Quarto workflowMaterial for nbdev workflowInstall:$pipinstallnotebooknbdev
$nbdev_install_quartoInstall:$pipinstallnotebooknbdev
$nbdev_install_quarto
$pipinstallnbdev-mkdocsSetup:$nbdev_new
$nbdev_install_hooks
$visettings.ini
$pipinstall-e'.[dev]'Setup:$nbdev_new
$nbdev_install_hooks
$visettings.ini
$pipinstall-e'.[dev]'$nbdev_mkdocsnew
$vimkdocs/mkdocs.ymlDevelopment:# Edit files$nbdev_previewDevelopment:# Edit files$nbdev_mkdocspreviewCommit changes:$nbdev_prepare
$gitcommit-am“Commitmessage”
$gitpushCommit changes:$nbdev_mkdocsprepare
$gitcommit-am“Commitmessage”
$gitpushQuick startThe 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 theUser
Guide.Installnbdev-mkdocs is published as a Python package and can be installed with
pip:pipinstallnbdev-mkdocsNote thatnbdev-mkdocsmust be installed in the same Python
environment as nbdev.If the installation was successful, you should now have thenbdev-mkdocsinstalled on your system. Run the below command from
the terminal to see the full list of available commands:nbdev_mkdocs--helpUsage: 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.                     │
│ readme                   Updates the README.md file from the 'readme_nb'     │
│                          notebook. Unless explicitly changed in the          │
│                          settings.ini file, the 'readme_nb' points to the    │
│                          'index.ipynb' notebook in the 'nbs_path' directory. │
│ social-image             Command for generating a custom social share image. │
╰──────────────────────────────────────────────────────────────────────────────╯SetupAfter installing nbdev-mkdocs, bootstrap your project documentation by
executing the following command from the project’s root directory:nbdev_mkdocsnewUsing information from the project’s settings.ini file, the above
command creates files and directories required to build the
documentation and saves it in themkdocssubdirectory.Note: You should only run thenbdev_mkdocs newcommand once for the
project to initialise the files required for building Material for
MkDocs documentation.Preview changesnbdev_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, runpip install -e '.[dev]'command before running thenbdev_mkdocs preparecommand.nbdev_mkdocspreviewPrepare changesTo prepare your changes for Git push, we recommend executing the
following commands:First, run thenbdev_mkdocs preparecommand in the terminal. This
command exports the library, runs tests, and cleans the notebooks.nbdev_mkdocsprepareThen, run thenbdev_mkdocs readmecommand to update the README.md file
from the ‘readme_nb’ notebook. By default, ‘readme_nb’ points to
‘index.ipynb’ notebook in the ‘nbs_path’ unless modified in the
settings.ini file.This command does everything the ‘nbdev_readme’ command does, plus it
generates symbol references that are compatible with ‘Material for
nbdev’.nbdev_mkdocsreadmeFinally, double-check your settings.ini file to ensure that it has all
of the correct information. Then commit and push your additions to
GitHub:gitcommit-am'Commit Message'gitpushCopyrightCopyright © 2022 onwards airt technologies ltd, Inc.LicenseThis project is licensed under the terms of theApache License
2.0