Skip to content

MacHu-GWU/sqlalchemy_upsert_kit-project / .claude/skills/pywf-oss-base

pywf-oss-base

Flagged

Shared conventions, references, and scripts of the pywf-oss skills for pywf open-source Python libraries: setup, layout, code style, tests, user docs and the agent skills that hold API and maintenance knowledge, CI and hosting, release, dependencies, and secrets. Load it before ad-hoc work on modules, tests, or docs in such a repo, for a question about these conventions, or when unsure which pywf-oss skill fits a job.

FileKindSize
SKILL.mdskill md6.5 KB
assets/community-skills.tomlconfig2.4 KB
assets/notebook-page-template.ipynbother1.1 KB
assets/raw-rst-cell.jsonconfig255 B
references/00-authoring-references.mdmarkdown6.3 KB
references/01-secrets.mdmarkdown3.0 KB
references/02-machine-setup.mdmarkdown3.2 KB
references/03-mise.mdmarkdown2.1 KB
references/04-python-versions.mdmarkdown1.8 KB
references/05-uv-dependencies.mdmarkdown2.0 KB
references/06-ruff.mdmarkdown1.9 KB
references/07-repo-layout.mdmarkdown2.3 KB
references/08-package-files.mdmarkdown3.9 KB
references/09-code-style.mdmarkdown5.6 KB
references/10-test-layout.mdmarkdown4.1 KB
references/11-test-writing.mdmarkdown2.1 KB
references/12-coverage.mdmarkdown1.1 KB
references/13-sphinx.mdmarkdown5.6 KB
references/14-docfly.mdmarkdown2.2 KB
references/15-furo.mdmarkdown1.4 KB
references/16-sphinx-design.mdmarkdown5.8 KB
references/17-nbsphinx.mdmarkdown5.0 KB
references/18-knowledge-channels.mdmarkdown3.8 KB
references/19-github-actions.mdmarkdown3.7 KB
references/20-codecov.mdmarkdown1.3 KB
references/21-readthedocs.mdmarkdown1.7 KB
references/22-versioning-and-changelog.mdmarkdown3.0 KB
references/23-release.mdmarkdown1.3 KB
references/24-dependency-upgrades.mdmarkdown3.2 KB
references/25-python-release-cycle.mdmarkdown1.4 KB
references/26-community-skills.mdmarkdown5.0 KB
references/27-skill-family-workflow.mdmarkdown6.5 KB
scripts/check_doc_xrefs.pyscript3.4 KB
scripts/check_one_import_per_line.pyscript4.2 KB
scripts/check_skill_family.pyscript6.5 KB
scripts/check_test_layout.pyscript6.2 KB
scripts/install_community_skill.pyscript8.6 KB
scripts/update_skill_index.pyscript4.1 KB

references/17-nbsphinx.md

View on GitHub
---
description: "Notebook docs pages with nbsphinx: raw reStructuredText cells with the exact cell JSON, the page skeleton, code cell style, and executing and committing outputs. Read when creating or editing a .ipynb docs page."
---

# nbsphinx Notebooks

A docs page can be `index.ipynb` instead of `index.rst`. nbsphinx renders it, and `.. autotoctree::` picks it up like any other page. Folder naming (`14-docfly.md`), labels, and cross-references (`13-sphinx.md`) work as for `.rst` pages.

Use a notebook when the page teaches by running code and real output helps the reader; use `.rst` for concepts and design notes.

---

## 1. The three cell types

| Cell | Used for | Rendered as |
| :--- | :--- | :--- |
| `code` | Runnable examples, with committed outputs | Code plus its output |
| `markdown` | Prose, lists, tables, images, and links. A link to another page uses its source path (`[text](../01-Some-Page/index.rst)` or `.ipynb`); nbsphinx turns it into the HTML link. | Markdown |
| `raw` with `raw_mimetype: text/restructuredtext` | Anything that needs Sphinx: the labeled page title, `:ref:` / `:class:` / `:func:` cross-references, directives (`.. note::`, `.. code-block::`, sphinx-design widgets from `16-sphinx-design.md`) | reStructuredText, parsed by Sphinx |

Markdown cells cannot use Sphinx roles or directives; put such a piece in a raw reST cell (<https://nbsphinx.readthedocs.io/en/0.9.8/raw-cells.html>).

---

## 2. Raw reST cell: the exact JSON

In JupyterLab or PyCharm, set the cell type to *Raw* and the *Raw NBConvert Format* to *reStructuredText*. On disk:

```json
{
  "cell_type": "raw",
  "id": "a1b2c3d4",
  "metadata": {
    "raw_mimetype": "text/restructuredtext"
  },
  "source": [
    ".. _getting-started:\n",
    "\n",
    "Getting Started\n",
    "==============================================================================\n"
  ]
}
```

- `metadata.raw_mimetype` must be exactly `text/restructuredtext`. Without it, nbsphinx drops the cell from the HTML.
- `source` is a list of lines, each ending in `\n` except possibly the last.
- `assets/raw-rst-cell.json` in the base skill is a copy-ready template of this cell, and `assets/notebook-page-template.ipynb` a minimal page in the skeleton of section 3.

---

## 3. Page skeleton

1. **Raw reST cell:** the page label and title with a 78-character `=` underline (as above), giving the page its `:ref:` target and sidebar title.
2. **Markdown cell:** one paragraph on what the page shows and who it is for.
3. **Then alternate** markdown cells (`##` section headings, explanations) and code cells, with a raw reST cell wherever a cross-reference or directive is needed.

Example raw cell in the middle of a page:

```rst
Every result is a :class:`~<package_name>.module_name.ClassName`; see :ref:`getting-started`
for how to create one.

.. note::

    One sentence the reader must not miss.
```

The sample page `docs/source/02-Sample-Jupyter-Notebook-Document/index.ipynb` of a template repo is a working example of everything on this page.

From nbsphinx 0.9.8 on, a raw-cell title shows in the sidebar and in `.. autotoctree::`. Some versions have lost that sidebar link (nbsphinx PR #834): if a page vanishes from the sidebar after an nbsphinx upgrade, move the title into a Markdown `# Title` cell, and keep the label in a raw cell above it.

---

## 4. Code cells: style

The reader learns one step at a time, so plain and explicit beats short.

- **One step and one result per cell.** Show a value as the last expression or with `print(f"{x = }")`; three values take three cells.
- Write the code a user would write: named variables, plain `for` loops, no clever comprehensions, lambdas, or demo-only helper functions.
- Show an expected error explicitly, one per cell:

  ```python
  try:
      do_bad_thing()
  except ValueError as e:
      print(f"{type(e).__name__}: {e}")
  ```

- Import from the public API (`from <package_name>.api import ClassName`), exactly as users would.
- Never put inline code inside bold in markdown (`**``x``**`); some editors render it badly.
- Never write secrets, account ids, or personal paths in a cell; read them from environment variables.

---

## 5. Editing and running

- Edit cells with the `NotebookEdit` tool or with `nbformat` in a script, never by hand-editing output JSON.
- Outputs are committed, because the hosted docs show what the file stores. Execute the notebook locally before committing:

  ```bash
  .venv/bin/jupyter nbconvert --to notebook --execute --inplace docs/source/02-Some-Topic/index.ipynb
  ```

  `ipykernel` comes with the `doc` extra, so `mise run inst` is enough.
- If a notebook needs credentials or services the hosted build lacks, set `nbsphinx_execute = "never"` in `conf.py`, so the build uses only committed outputs.
- `mise run notebook-to-markdown` converts the notebooks to Markdown, for an AI to read the docs without the JSON noise.
- Then build and check it like any page (`13-sphinx.md` section 4): raw cells render, cross-references resolve, and the page is in the sidebar.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall