Documentation Only Sites

How to create nbdev powered docs without a library!

Background

While nbdev is great for authoring software, you may wish to utilize the power of nbdev for the purposes of documenting existing code, or use various utilities of nbdev without having to write a python library. For example, you can use the following features of nbdev without creating a python package:

• Custom nbdev directives such as #|hide_line.
• Testing with nbdev_test.
• Automated entity linking with doclinks.
• Rendering API documentation with docments and show_doc.

Setup

To setup a documentation only site, you can follow these steps:

1. Create a nbdev repo the usual way, using nbdev_new
2. Remove library files

rm setup.py .github/workflows/test.yaml nbs/00_core.ipynb

3. Remove your library folder (this will be the lib_path field in settings.ini):

rm -rf <lib_path>

Usage

After setting up your project, you can use various nbdev utilities per usual:

• nbdev_preview for previewing your site
• nbdev_test for testing your docs locally
• Custom nbdev directives will be available to you (but you must be careful not to use irrelevant ones like #|export).
• If you created your nbdev docs site on GitHub, GitHub Actions will publish your docs for you automatically as described here.
• You can publish your docs on other platforms as described here.

Demo

A minimal example of a documentation-only site is located here.