write-project-docs

Write project docs

Three parts: (1) documenting the notebooks themselves, (2) optionally publishing an llms.txt on the project's docs site, and (3) optionally theming that docs site dark with a light/dark toggle. Part 1 is the common case; parts 2 and 3 are one-time setups you'll rarely repeat per-project.

Part 1: documenting notebooks

If slmn is importable in this environment, prefer its tools over hand-editing notebook JSON:

• slmn.nbtools.write_nb_docs(path, notes=[[after_id, source], ...], patches=[[cell_id, new_source], ...]) for one notebook.
• slmn.nbtools.write_project_docs(specs, llms_txt=None) for several notebooks at once -- specs is {notebook_path: {'notes': ..., 'patches': ...}}. It validates every cell id in every notebook before writing any of them, so a bad id can't leave some notebooks half-edited.

Both take two kinds of edit -- notes (new markdown cells, purely additive) and patches (replace an existing cell's source outright). Deciding which one to use for a given cell is the part that needs judgment, not a fixed rule:

Preserve vs. overwrite

Default to notes. Adding a heading/summary next to existing content is always safe -- worst case it's slightly redundant, and that's trivial to fix later. Reach for patches only when you're confident the existing cell is disposable.

A cell is disposable if it's near-verbatim nbdev/quarto scaffolding -- the same boilerplate every fresh nbdev_new-generated project ships with, not anything a human wrote for this project. Known examples to check the exact wording of before treating something new as boilerplate (the wording can drift between nbdev versions):

• "This file will become your README and also the index of your documentation."
• The whole ## Developer Guide section ("If you are new to using nbdev here are some useful pointers to get you started.", "### Install <pkg> in Development mode", the pip install -e . / nbdev_prepare code block).
• ## Usage / ### Installation boilerplate with unfilled conda/PyPI placeholders (pip install git+https://github.com/..., conda install -c ..., pip install ...) when the package in fact isn't published to conda/PyPI yet -- these aren't just generic, they're actively wrong.
• ### Documentation boilerplate pointing at [docs]/[repo]/[pypi]/[conda] link placeholders with no project-specific content.