# Material for nbdev
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
------------------------------------------------------------------------
**Documentation**: https://nbdev-mkdocs.airt.ai
**Source Code**: https://github.com/airtai/nbdev-mkdocs
------------------------------------------------------------------------
## Getting Started
  
------------------------------------------------------------------------
**Material for nbdev** is a
<a href="https://nbdev.fast.ai/" target="_blank">nbdev</a> extension
that allows you to use
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank">Material
for MkDocs</a> to 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 using
<a href="https://docstring-gen.airt.ai/" target="_blank">docstring-gen</a>
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.
### Workflow
Here’s a quick comparison of Quarto and Material for nbdev development
workflows:
<!-- | **Quarto workflow** | **Material for nbdev workflow** |
|--- |--- |
| Install:<br>> pip install notebook nbdev<br>> nbdev_install_quarto | Install:<br>> pip install notebook nbdev<br>> nbdev_install_quarto<br>**> pip install nbdev-mkdocs** |
| Setup:<br>> nbdev_new<br>> nbdev_install_hooks<br>> vi settings.ini<br>> pip install -e '.[dev]' | Setup:<br>> nbdev_new<br>> nbdev_install_hooks<br>> vi settings.ini<br>> pip install -e '.[dev]'<br>**> nbdev_mkdocs new**<br>**> vi mkdocs/mkdocs.yml** |
| Development:<br># Edit files<br>> nbdev_preview | Development:<br># Edit files<br>**> nbdev_mkdocs preview**<br> |
| Commit changes:<br>> nbdev_prepare<br>> git commit -am “Commit message”<br>> git push | Commit changes:<br>**> nbdev_mkdocs prepare**<br>> git commit -am “Commit message”<br>> git push | -->
<table>
<thead>
<tr>
<th>
<strong>Quarto workflow</strong>
</th>
<th>
<strong>Material for nbdev workflow</strong>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Install:
``` shell
$ pip install notebook nbdev
$ nbdev_install_quarto
```
</td>
<td>
Install:
``` shell
$ pip install notebook nbdev
$ nbdev_install_quarto
$ pip install nbdev-mkdocs
```
</td>
</tr>
<tr>
<td>
Setup:
``` shell
$ nbdev_new
$ nbdev_install_hooks
$ vi settings.ini
$ pip install -e '.[dev]'
```
</td>
<td>
Setup:
``` shell
$ nbdev_new
$ nbdev_install_hooks
$ vi settings.ini
$ pip install -e '.[dev]'
$ nbdev_mkdocs new
$ vi mkdocs/mkdocs.yml
```
</td>
</tr>
<tr>
<td>
Development:
``` shell
# Edit files
$ nbdev_preview
```
</td>
<td>
Development:
``` shell
# Edit files
$ nbdev_mkdocs preview
```
</td>
</tr>
<tr>
<td>
Commit changes:
``` shell
$ nbdev_prepare
$ git commit -am “Commit message”
$ git push
```
</td>
<td>
Commit changes:
``` shell
$ nbdev_mkdocs prepare
$ git commit -am “Commit message”
$ git push
```
</td>
</tr>
</tbody>
</table>
### 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
<a href="https://nbdev-mkdocs.airt.ai/latest/guides/Basic_User_Guide/">User
Guide</a>.
### Install
nbdev-mkdocs is published as a Python package and can be installed with
pip:
``` shell
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:
``` shell
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:
``` shell
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.
``` shell
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.
``` shell
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’.
``` shell
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:
``` shell
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](https://github.com/airtai/nbdev-mkdocs/blob/main/LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/airtai/nbdev-mkdocs",
"name": "nbdev-mkdocs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "nbdev jupyter notebook python mkdocs material",
"author": "airt",
"author_email": "info@airt.ai",
"download_url": "https://files.pythonhosted.org/packages/35/95/a523316e3a10d2a92fddec5bce42e9923b00886411fffc9bd91678a378df/nbdev-mkdocs-0.6.1.tar.gz",
"platform": null,
"description": "# Material for nbdev\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n\n\n------------------------------------------------------------------------\n\n**Documentation**: https://nbdev-mkdocs.airt.ai\n\n**Source Code**: https://github.com/airtai/nbdev-mkdocs\n\n------------------------------------------------------------------------\n\n## Getting Started\n\n  \n\n\n\n\n\n\n\n\n------------------------------------------------------------------------\n\n**Material for nbdev** is a\n<a href=\"https://nbdev.fast.ai/\" target=\"_blank\">nbdev</a> extension\nthat allows you to use\n<a href=\"https://squidfunk.github.io/mkdocs-material/\" target=\"_blank\">Material\nfor MkDocs</a> to generate documentation for nbdev projects.\n\nThe key features are:\n\n- **Material style documentation**: Effortlessly create material style\n documentation for your nbdev projects with Material for MkDocs, a\n theme that provides a sleek and modern design for your documentation.\n- **Auto generate docstrings**: Instantly generate docstrings for your\n Python code using\n <a href=\"https://docstring-gen.airt.ai/\" target=\"_blank\">docstring-gen</a>\n library, a tool that automatically generates docstrings for your\n functions and classes using Codex.\n- **Create stunning social media share images**: Boost your project\u2019s\n visibility by creating striking social share images using DALL-E.\n- **Customizability**: Add guides, release notes, customise the\n navigation menu and configure the Material for MkDocs easily to suit\n your project needs. With this documentation tool, you have more\n control over the look and feel of your documentation, allowing you to\n create a unique and personalized experience for your users.\n\n### Workflow\n\nHere\u2019s a quick comparison of Quarto and Material for nbdev development\nworkflows:\n\n<!-- | **Quarto workflow** | **Material for nbdev workflow** |\n|--- |--- |\n| Install:<br>> pip install notebook nbdev<br>> nbdev_install_quarto | Install:<br>> pip install notebook nbdev<br>> nbdev_install_quarto<br>**> pip install nbdev-mkdocs** |\n| Setup:<br>> nbdev_new<br>> nbdev_install_hooks<br>> vi settings.ini<br>> pip install -e '.[dev]' | Setup:<br>> nbdev_new<br>> nbdev_install_hooks<br>> vi settings.ini<br>> pip install -e '.[dev]'<br>**> nbdev_mkdocs new**<br>**> vi mkdocs/mkdocs.yml** |\n| Development:<br># Edit files<br>> nbdev_preview | Development:<br># Edit files<br>**> nbdev_mkdocs preview**<br> |\n| Commit changes:<br>> nbdev_prepare<br>> git commit -am \u201cCommit message\u201d<br>> git push | Commit changes:<br>**> nbdev_mkdocs prepare**<br>> git commit -am \u201cCommit message\u201d<br>> git push | -->\n<table>\n<thead>\n<tr>\n<th>\n<strong>Quarto workflow</strong>\n</th>\n<th>\n<strong>Material for nbdev workflow</strong>\n</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>\n\nInstall:\n\n``` shell\n$ pip install notebook nbdev\n$ nbdev_install_quarto\n```\n\n</td>\n<td>\n\nInstall:\n\n``` shell\n$ pip install notebook nbdev\n$ nbdev_install_quarto\n$ pip install nbdev-mkdocs\n```\n\n</td>\n</tr>\n<tr>\n<td>\n\nSetup:\n\n``` shell\n$ nbdev_new\n$ nbdev_install_hooks\n$ vi settings.ini\n$ pip install -e '.[dev]'\n```\n\n</td>\n<td>\n\nSetup:\n\n``` shell\n$ nbdev_new\n$ nbdev_install_hooks\n$ vi settings.ini\n$ pip install -e '.[dev]'\n$ nbdev_mkdocs new\n$ vi mkdocs/mkdocs.yml\n```\n\n</td>\n</tr>\n<tr>\n<td>\n\nDevelopment:\n\n``` shell\n# Edit files\n$ nbdev_preview\n```\n\n</td>\n<td>\n\nDevelopment:\n\n``` shell\n# Edit files\n$ nbdev_mkdocs preview\n```\n\n</td>\n</tr>\n<tr>\n<td>\n\nCommit changes:\n\n``` shell\n$ nbdev_prepare\n$ git commit -am \u201cCommit message\u201d\n$ git push\n```\n\n</td>\n<td>\n\nCommit changes:\n\n``` shell\n$ nbdev_mkdocs prepare\n$ git commit -am \u201cCommit message\u201d\n$ git push\n```\n\n</td>\n</tr>\n</tbody>\n</table>\n\n### Quick start\n\nThe following quick start guide will walk you through installing and\nconfiguring nbdev-mkdocs for an existing nbdev project. It also assumes\nyou\u2019ve already initialized your project with nbdev and installed all of\nthe required libraries.\n\nFor detailed installation instructions and configuration options, please\nsee the\n<a href=\"https://nbdev-mkdocs.airt.ai/latest/guides/Basic_User_Guide/\">User\nGuide</a>.\n\n### Install\n\nnbdev-mkdocs is published as a Python package and can be installed with\npip:\n\n``` shell\npip install nbdev-mkdocs\n```\n\nNote that `nbdev-mkdocs` must be installed in the same Python\nenvironment as nbdev.\n\nIf the installation was successful, you should now have the\n**nbdev-mkdocs** installed on your system. Run the below command from\nthe terminal to see the full list of available commands:\n\n``` shell\nnbdev_mkdocs --help\n```\n\n \n Usage: nbdev_mkdocs [OPTIONS] COMMAND [ARGS]... \n \n \u256d\u2500 Options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n \u2502 --install-completion Install completion for the current shell. \u2502\n \u2502 --show-completion Show completion for the current shell, to copy \u2502\n \u2502 it or customize the installation. \u2502\n \u2502 --help Show this message and exit. \u2502\n \u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n \u256d\u2500 Commands \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n \u2502 delete-pre-release-docs Deletes deployed pre-release documentation \u2502\n \u2502 versions. \u2502\n \u2502 docs Prepares files in 'mkdocs/docs' and then runs \u2502\n \u2502 'mkdocs build' command on them. \u2502\n \u2502 docstring Command for adding docstrings to classes and \u2502\n \u2502 methods that don't have one using docstring-gen \u2502\n \u2502 library. \u2502\n \u2502 new Creates files in 'mkdocs' subdirectory needed for \u2502\n \u2502 other 'nbdev_mkdocs' subcommands. \u2502\n \u2502 prepare Runs tests and prepares files in 'mkdocs/docs' and \u2502\n \u2502 then runs 'mkdocs build' command on them. \u2502\n \u2502 preview Prepares files in 'mkdocs/docs' and then runs \u2502\n \u2502 'mkdocs serve' command on them. \u2502\n \u2502 readme Updates the README.md file from the 'readme_nb' \u2502\n \u2502 notebook. Unless explicitly changed in the \u2502\n \u2502 settings.ini file, the 'readme_nb' points to the \u2502\n \u2502 'index.ipynb' notebook in the 'nbs_path' directory. \u2502\n \u2502 social-image Command for generating a custom social share image. \u2502\n \u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n\n#### Setup\n\nAfter installing nbdev-mkdocs, bootstrap your project documentation by\nexecuting the following command from the project\u2019s root directory:\n\n``` shell\nnbdev_mkdocs new\n```\n\nUsing information from the project\u2019s settings.ini file, the above\ncommand creates files and directories required to build the\ndocumentation and saves it in the **mkdocs** subdirectory.\n\nNote: You should only run the **nbdev_mkdocs new** command once for the\nproject to initialise the files required for building Material for\nMkDocs documentation.\n\n#### Preview changes\n\nnbdev_mkdocs lets you preview your changes as you write your\ndocumentation. Execute the following command from the project root\ndirectory to start a local server, and preview your documentation:\n\n**Note**: If you haven\u2019t already installed your library locally, run\n`pip install -e '.[dev]'` command before running the\n`nbdev_mkdocs prepare` command.\n\n``` shell\nnbdev_mkdocs preview\n```\n\n#### Prepare changes\n\nTo prepare your changes for Git push, we recommend executing the\nfollowing commands:\n\nFirst, run the `nbdev_mkdocs prepare` command in the terminal. This\ncommand exports the library, runs tests, and cleans the notebooks.\n\n``` shell\nnbdev_mkdocs prepare\n```\n\nThen, run the `nbdev_mkdocs readme` command to update the README.md file\nfrom the \u2018readme_nb\u2019 notebook. By default, \u2018readme_nb\u2019 points to\n\u2018index.ipynb\u2019 notebook in the \u2018nbs_path\u2019 unless modified in the\nsettings.ini file.\n\nThis command does everything the \u2018nbdev_readme\u2019 command does, plus it\ngenerates symbol references that are compatible with \u2018Material for\nnbdev\u2019.\n\n``` shell\nnbdev_mkdocs readme\n```\n\nFinally, double-check your settings.ini file to ensure that it has all\nof the correct information. Then commit and push your additions to\nGitHub:\n\n``` shell\ngit commit -am'Commit Message'\ngit push\n```\n\n## Copyright\n\nCopyright \u00a9 2022 onwards airt technologies ltd, Inc.\n\n## License\n\nThis project is licensed under the terms of the [Apache License\n2.0](https://github.com/airtai/nbdev-mkdocs/blob/main/LICENSE)\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Extension of nbdev for generating documentation using Material for Mkdocs instead of Quarto",
"version": "0.6.1",
"project_urls": {
"Homepage": "https://github.com/airtai/nbdev-mkdocs"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python",
"mkdocs",
"material"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e6238615272a2cf4d28d972e3fc5a90460102e356b5cf5da928111e93cf48f87",
"md5": "49abd06a0bb2eff8bf9ba065dc2ffee9",
"sha256": "7e7adcdcb133045cf6f8547d29c0b70c4c8e753bf1d86d1abf6f7cc2d5551513"
},
"downloads": -1,
"filename": "nbdev_mkdocs-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "49abd06a0bb2eff8bf9ba065dc2ffee9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 158758,
"upload_time": "2024-02-21T06:33:26",
"upload_time_iso_8601": "2024-02-21T06:33:26.612588Z",
"url": "https://files.pythonhosted.org/packages/e6/23/8615272a2cf4d28d972e3fc5a90460102e356b5cf5da928111e93cf48f87/nbdev_mkdocs-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3595a523316e3a10d2a92fddec5bce42e9923b00886411fffc9bd91678a378df",
"md5": "d6c3488ae874c42a6652641f9fe41f2e",
"sha256": "cc575c5e0b25ef108d3f4c8889e5d4720a669a77f7e875699a1fa99a18072e88"
},
"downloads": -1,
"filename": "nbdev-mkdocs-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "d6c3488ae874c42a6652641f9fe41f2e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 156496,
"upload_time": "2024-02-21T06:33:30",
"upload_time_iso_8601": "2024-02-21T06:33:30.321187Z",
"url": "https://files.pythonhosted.org/packages/35/95/a523316e3a10d2a92fddec5bce42e9923b00886411fffc9bd91678a378df/nbdev-mkdocs-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-21 06:33:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "airtai",
"github_project": "nbdev-mkdocs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nbdev-mkdocs"
}
JSON
