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/13-sphinx.md

View on GitHub
---
description: "Sphinx without theme or extensions: conf.py, reStructuredText heading and label rules, the exact cross-reference forms and why a target silently fails to resolve, the small built-in extensions, and building and checking the docs, including the AI visual check. Read when writing reStructuredText or a docstring cross-reference, or checking a local docs build."
---

# Sphinx

The docs are a Sphinx project in `docs/source/`, configured by `conf.py`, with reStructuredText pages. The theme and each larger extension have their own reference.

---

## 1. reStructuredText conventions

Heading underlines are exactly **78 characters**, at three levels:

```rst
Page Title
==============================================================================

Section
------------------------------------------------------------------------------

Subsection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```

- **Labels** go right above a title that other pages link to. They are kebab-case and unique across the project:

  ```rst
  .. _getting-started:

  Getting Started
  ==============================================================================
  ```

- **Code:** inline ``` ``code`` ```; blocks with `.. code-block:: python`.
- **External links:** `` `text <https://...>`_ ``.
- **Admonitions** (`.. note::`, `.. warning::`): sparingly.

---

## 2. Cross-references

These roles work the same in `.rst` pages, docstrings, and anywhere else reStructuredText is parsed. The sample page `docs/source/01-Sample-RestructuredText-Document/index.rst` of a template repo uses every form below.

### 2.1 Python objects

Always write the **full dotted path from the defining module**, not from the `api.py` re-export, then pick the display form that reads best:

| Target | Full path, displayed as written | Preferred display form | Renders as |
| :--- | :--- | :--- | :--- |
| Module | ``:mod:`<package_name>.module_name` `` | (same) | `<package_name>.module_name` |
| Class | ``:class:`<package_name>.module_name.ClassName` `` | ``:class:`~<package_name>.module_name.ClassName` `` | `ClassName` |
| Method | ``:meth:`<package_name>.module_name.ClassName.method_name` `` | ``:meth:`ClassName.method_name <<package_name>.module_name.ClassName.method_name>` `` | `ClassName.method_name()` |
| Function | ``:func:`<package_name>.module_name.func_name` `` | ``:func:`~<package_name>.module_name.func_name` `` | `func_name()` |
| Function, with its module | | ``:func:`module_name.func_name <<package_name>.module_name.func_name>` `` | `module_name.func_name()` |
| Module-level constant | ``:attr:`<package_name>.module_name.CONSTANT_NAME` `` | ``:attr:`~<package_name>.module_name.CONSTANT_NAME` `` | `CONSTANT_NAME` |
| Class attribute, field, or property | ``:attr:`<package_name>.module_name.ClassName.attr_name` `` | ``:attr:`ClassName.attr_name <<package_name>.module_name.ClassName.attr_name>` `` | `ClassName.attr_name` |

- `~` keeps only the last name. Use it when the context makes the module obvious.
- `title <target>` displays any text. For a method, show `ClassName.method_name`: a bare `method_name` loses its class.
- **Match the role to the object type:** `:meth:` for methods, `:func:` for functions, `:attr:` for constants, attributes, and fields. Sphinx may resolve a mismatched role, but renders it wrong (such as a trailing `()`).

### 2.2 Why a target silently fails

A Python target resolves only if autodoc documented the object: a function, class, or method needs a docstring, and a constant or field a `#:` comment (`09-code-style.md`). An unresolved target renders as plain code instead of a link, and **Sphinx gives no warning**. After a build, run:

```bash
python ${CLAUDE_SKILL_DIR}/../pywf-oss-base/scripts/check_doc_xrefs.py
```

It lists every cross-reference that did not become a link. Add `--include_api` to also scan the generated API pages.

### 2.3 Pages, sections, and the standard library

| Target | Syntax |
| :--- | :--- |
| A labeled section or page | ``:ref:`getting-started` ``, or ``:ref:`custom text <getting-started>` `` |
| Another doc file, relative to the current page | ``:doc:`../03-Some-Topic/index` `` |
| Another doc file, from `docs/source/` | ``:doc:`/03-Some-Topic/index` `` |
| Python standard library (through intersphinx) | ``:class:`pathlib.Path` ``, ``:func:`json.dumps` `` |

---

## 3. Small extensions

Enabled in `conf.py`, with no reference of their own:

| Extension | What it does |
| :--- | :--- |
| `sphinx.ext.intersphinx` | Resolves standard library cross-references |
| `sphinx.ext.viewcode` | Adds "[source]" links next to API entries |
| `sphinx-copybutton` | Adds a copy button to code blocks |
| `sphinx-jinja` | Renders data from code through `.. jinja:: doc_data`, defined in `<package_name>/docs/__init__.py` |

`rst_prolog` includes `_static/.custom-style.rst`, which defines the custom roles (colors, strike, and so on) available on every page.

---

## 4. Build and check

```bash
mise run build-doc   # clean build into docs/build/html
mise run view-doc    # open it in the browser
```

A docs change is done when:

- `build-doc` finishes with no new warnings;
- the cross-reference check reports 0 unresolved;
- the page appears in the sidebar with the right title and order.

**Visual check by an AI:** in the Claude desktop app, open the built site with the browser pane's `preview_start` and the `docs-html` configuration in `.claude/launch.json`, which serves `docs/build/html` over HTTP. Never open the files as `file://`: the pane then shows a snapshot without CSS, so layout and theme cannot be judged. Humans keep using `mise run view-doc`; their browser loads CSS from `file://` fine.
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