Skip to content

docs(nav): give Plotting Prelude a title and put the four chapters in the sidebar - #584

Merged
breimanntools merged 1 commit into
masterfrom
doc/getting-started-nav
Sep 18, 2026
Merged

breimanntools merged 1 commit into
masterfrom
doc/getting-started-nav

Conversation

@breimanntools

Copy link
Copy Markdown
Owner

Two linked defects in Getting Started.

1. Plotting Prelude had no title. The first cell of tutorials/plotting_prelude.ipynb was a raw cell, not markdown. nbsphinx passes a raw cell through verbatim, so # Plotting Prelude never became a heading: the page had no title, rendered the hash as literal text glued onto the first paragraph, and appeared in the toctree as <no title>. It is the only one of the four Getting Started notebooks with this defect — the other three open with markdown.

2. The sidebar showed the wrong things. docs/source/getting_started.rst contained no toctree at all. The four notebooks were body-text :doc: links, which render as a list but wire nothing into navigation, so the sidebar fell back to the page's own sections (Quick start / The two APIs / Decision Map) instead of the four chapters.

They had to be fixed together: a toctree entry takes its target's title, so Plotting Prelude would have appeared as <no title> in the sidebar.

Verification (full build, inspecting the generated HTML)

<title>  : "Plotting Prelude — AAanalysis"   (was <no title>)
first h1 : "Plotting Prelude"                (was none)
literal "# Plotting Prelude" in body: gone

Getting Started sidebar children:
  A minimal CPP analysis      -> generated/tutorial0_minimal.html
  Quick start with AAanalysis -> generated/tutorial1_quick_start.html
  Slow start with AAanalysis  -> generated/tutorial1_slow_start.html
  Plotting Prelude            -> generated/plotting_prelude.html

🤖 Generated with Claude Code

… the sidebar

Two linked defects in Getting Started.

The first cell of tutorials/plotting_prelude.ipynb was a `raw` cell, not
markdown. nbsphinx passes a raw cell through verbatim, so "# Plotting
Prelude" never became a heading: the page had no title, rendered the hash
as literal text glued onto the first paragraph, and appeared in the
toctree as "<no title>". It is the only one of the four Getting Started
notebooks with this defect; the other three open with markdown.

The second: docs/source/getting_started.rst contained no toctree at all.
The four notebooks were body-text :doc: links, which render as a list but
wire nothing into the navigation, so the sidebar fell back to the page's
own sections - "Quick start / The two APIs / Decision Map" - instead of
the four chapters.

They had to be fixed together: a toctree entry takes the target's title,
so Plotting Prelude would have shown as "<no title>" in the sidebar.

Verified on a full build:
  <title>  : "Plotting Prelude - AAanalysis"   (was <no title>)
  first h1 : "Plotting Prelude"                (was none)
  literal "# Plotting Prelude" in the body: gone
  sidebar  : the four chapters, each linking to its generated page

Co-Authored-By: Claude Fable 5.1 <[email protected]>
@codecov

codecov Bot commented Sep 18, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.39%. Comparing base (3c11c90) to head (b0334c6).

Additional details and impacted files

Impacted file tree graph

@@           Coverage Diff           @@
##           master     #584   +/-   ##
=======================================
  Coverage   95.39%   95.39%           
=======================================
  Files         222      222           
  Lines       23387    23387           
  Branches     4073     4073           
=======================================
  Hits        22309    22309           
  Misses        631      631           
  Partials      447      447           
Components Coverage Δ
cpp_core 95.97% <ø> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@breimanntools
breimanntools merged commit 359c2ac into master Sep 18, 2026
26 checks passed
@breimanntools
breimanntools deleted the doc/getting-started-nav branch September 18, 2026 20:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant