airtai / nbdev-mkdocs

Extension to nbdev for generating docs with Material for Mkdocs
https://nbdev-mkdocs.airt.ai
Apache License 2.0
17 stars 2 forks source link
mkdocs mkdocs-material nbdev

Material for nbdev


Documentation: https://nbdev-mkdocs.airt.ai

Source Code: https://github.com/airtai/nbdev-mkdocs


Getting Started

PyPI PyPI -
Downloads PyPI -
Python Version

GitHub Workflow
Status

CodeQL Dependency
Review

GitHub


Material for nbdev is a nbdev extension that allows you to use Material for MkDocs to generate documentation for nbdev projects.

The key features are:

Workflow

Here’s a quick comparison of Quarto and Material for nbdev development workflows:

Quarto workflow Material for nbdev workflow
Install: ``` shell $ pip install notebook nbdev $ nbdev_install_quarto ``` Install: ``` shell $ pip install notebook nbdev $ nbdev_install_quarto $ pip install nbdev-mkdocs ```
Setup: ``` shell $ nbdev_new $ nbdev_install_hooks $ vi settings.ini $ pip install -e '.[dev]' ``` Setup: ``` shell $ nbdev_new $ nbdev_install_hooks $ vi settings.ini $ pip install -e '.[dev]' $ nbdev_mkdocs new $ vi mkdocs/mkdocs.yml ```
Development: ``` shell # Edit files $ nbdev_preview ``` Development: ``` shell # Edit files $ nbdev_mkdocs preview ```
Commit changes: ``` shell $ nbdev_prepare $ git commit -am “Commit message” $ git push ``` Commit changes: ``` shell $ nbdev_mkdocs prepare $ git commit -am “Commit message” $ git push ```

Quick start

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.

Install

nbdev-mkdocs is published as a Python package and can be installed with pip:

pip install nbdev-mkdocs

Note that 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:

nbdev_mkdocs --help
 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.                     │
│ 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. │
╰──────────────────────────────────────────────────────────────────────────────╯

Setup

After installing nbdev-mkdocs, bootstrap your project documentation by executing the following command from the project’s root directory:

nbdev_mkdocs new

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.

Preview changes

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.

nbdev_mkdocs preview

Prepare changes

To prepare your changes for Git push, we recommend executing the following commands:

First, run the nbdev_mkdocs prepare command in the terminal. This command exports the library, runs tests, and cleans the notebooks.

nbdev_mkdocs prepare

Then, run the nbdev_mkdocs readme command 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_mkdocs readme

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

Copyright © 2022 onwards airt technologies ltd, Inc.

License

This project is licensed under the terms of the Apache License 2.0