Extension of nbdev for generating documentation using Material for Mkdocs instead of Quarto
Project description
Getting Started
Material for nbdev is a nbdev extension that allows you to use Material for MkDocs to generate documentation for nbdev projects.
Workflow
Here’s a quick comparison of Quarto and Material for nbdev development workflows:
Quarto workflow | Material for nbdev workflow |
---|---|
Install: $ pip install notebook nbdev $ nbdev_install_quarto |
Install: $ pip install notebook nbdev $ nbdev_install_quarto $ pip install nbdev-mkdocs |
Setup: $ nbdev_new $ nbdev_install_hooks $ vi settings.ini $ nbdev_export $ pip install -e ‘.[dev]’ |
Setup: $ nbdev_new $ nbdev_install_hooks $ vi settings.ini $ nbdev_export $ pip install -e ‘.[dev]’ $ nbdev_mkdocs new $ vi mkdocs/mkdocs.yml |
Development: # Edit files $ nbdev_preview |
Development: # Edit files $ nbdev_mkdocs preview |
Commit changes: $ nbdev_prepare $ git commit -am “Commit message” $ git push |
Commit changes: $ 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, configuration options, and an End-To-End Walkthrough, please see the documentation.
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 ───────────────────────────────────────────────────────────────────╮
│ new Creates files in **mkdocs** subdirectory needed for other │
│ **nbdev_mkdocs** subcommands │
│ prepare 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 │
╰──────────────────────────────────────────────────────────────────────────────╯
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.
Build and prepare
Execute the following command to build the Python modules and install the library locally:
nbdev_export && pip install -e '.[dev]'
Then execute the following command to generate the Material for MkDocs documentation.
nbdev_mkdocs prepare
Running the above command will:
- Generate the markdown files from the notebooks and saves them to the mkdocs/docs/ directory.
- Builds the documentation from the generated markdown files and saves the resulting files to the mkdocs/site directory.
Preview
After the documentation has been successfully built, execute the following command to start a local server and preview the documentation.
nbdev_mkdocs preview
Copyright
Copyright © 2022 onwards airt technologies ltd, Inc.
License
This project is licensed under the terms of the Apache License 2.0
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for nbdev_mkdocs-0.0.1rc2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 52316eb1bcc24a67f4f51704f94de8abca70a80e7f48953d13718e937e2103c3 |
|
MD5 | ab82af51665638a1f9a53ee54b8ae577 |
|
BLAKE2b-256 | 36aff020bfb2565fb3f3f7fa7a02ab50bb86171629a4613956e484b208fc231e |