How the site is built#
Demos are MyST Markdown notebooks. Sphinx and MyST-NB run them and publish the executed pages.
Notebooks#
Each demo is a
.mdfile innotebooks/with notebook front matter. Edit it in JupyterLab through Jupytext (just notebook); it saves back to Markdown without outputs.A folder with an
index.mdgroups pages. The home page shows a card for each notebook and folder, through thenotebook-gallerydirective indocs/_ext/gallery.py.Add a demo’s dependencies to the
notebooksgroup inpyproject.toml.
Build#
just build-docsruns Sphinx, configured indocs/conf.py. Warnings fail the build.MyST-NB executes each notebook in the project environment and caches results in
_build/.jupyter_cache. A notebook reruns only when its code changes.Most demos need a Nominal
defaultprofile. Without one, those notebooks aren’t run and their pages have no outputs. The Reference pages need no profile.The theme is
nominal-sphinx-theme. Changes every Nominal site should share go there.
Publishing#
CI runs just check, just test and just build-docs. Pull requests get a docs preview. A push to
main deploys to GitHub Pages, and the docs hub at dev.nominal.io publishes the site too.
Commands#
Command |
Does |
|---|---|
|
Install dependencies and tools |
|
Open the notebooks in JupyterLab |
|
Preview at http://127.0.0.1:8000 |
|
Build into |
|
Lint, type-check and format |
|
Run the tests |
The Data section covers nbdemo.data.