Skip to content

docs: fix from_source rendering and promote bold pseudo-headings#155

Merged
janickm merged 1 commit into
NVIDIA:mainfrom
janickm:dev/janickm/fix-from-source-docs
Jun 17, 2026
Merged

docs: fix from_source rendering and promote bold pseudo-headings#155
janickm merged 1 commit into
NVIDIA:mainfrom
janickm:dev/janickm/fix-from-source-docs

Conversation

@janickm

@janickm janickm commented Jun 17, 2026

Copy link
Copy Markdown
Collaborator

What

The "Deriving an ideal target (IdealPinholeCameraModelParameters.from_source)"
block in the sensor models docs rendered weirdly and its references into the API
docs were missing. While fixing that, the same bold-paragraph-as-heading pattern
was applied consistently across the docs.

Changes

from_source rendering and API links (the original report)

  • The "Deriving an ideal target" and "Rectificator" blocks used bold paragraphs
    (**...**) as pseudo-headings. With a code literal inside the bold they
    rendered oddly and never showed up in the page table of contents. Promoted
    both to real RST subsection headings.
  • References to IdealPinholeCameraModelParameters.from_source / natural_fov
    and Rectificator / CameraModel were plain double-backtick literals, so they
    did not link into the API docs. Converted them to :meth: / :class:
    cross-references that resolve against the autodoc'd ncore.data and
    ncore.sensors modules.

Bold pseudo-headings promoted to a real sub-hierarchy

The same **...** pseudo-heading pattern was used throughout the docs. Promoted
the remaining standalone ones to real headings with a consistent hierarchy:

  • docs/data/sensor_models.rst: the camera/lidar/external-distortion model names
    (FTheta, Ideal Pinhole, OpenCV Pinhole, OpenCV Fisheye, Bivariate Windshield,
    Row-Offset Structured Spinning Lidar) become subsection headings. Each sat
    directly under a .. _label: cross-reference target, so the :ref: links that
    point at them now resolve to real titled sections (with permalink anchors) and
    appear in the page TOC. Their inline Mathematical Model / Parameters /
    Notation / Direction labels become nested sub-subsection headings.
  • docs/data/formats.rst: Label Type System / Encoding /
    Instance naming convention / Compat layer access become sub-subsections of
    "Camera Labels Component".
  • docs/tools/ncore_sequence_meta.rst: Global options / V4 sub-command options become subsections of "Options".
  • docs/data/storage_and_access.rst: Tradeoffs becomes a subsection of the
    ".itar" format section.

Mid-paragraph emphasis (e.g. **Example:**, **Forward distortion**) is left as
bold inline text, since those are not standalone headings.

Verification

bazel build //docs:ncore succeeds with no RST or cross-reference warnings (only
pre-existing unrelated nbsphinx deprecation notices). The rendered HTML confirms:

  • data/sensor_models.html: model names render as <h3> and their inline labels
    as nested <h4>; :ref: links resolve to real heading anchors (e.g.
    #ftheta-camera-model); and the from_source / natural_fov references link
    into apis/data.html#ncore.data.IdealPinholeCameraModelParameters.from_source
    (and .natural_fov).
  • data/formats.html, tools/ncore_sequence_meta.html and
    data/storage_and_access.html show the promoted headings at the expected
    nesting levels.

@janickm janickm force-pushed the dev/janickm/fix-from-source-docs branch from 7cf1a31 to 46de35f Compare June 17, 2026 13:22
The 'Deriving an ideal target' and 'Rectificator' blocks in the sensor
models docs used bold paragraphs as pseudo-headings, which rendered
weirdly (a literal inside bold) and never appeared in the page table of
contents. Promote both to real RST subsection headings.

References to IdealPinholeCameraModelParameters.from_source/natural_fov
and Rectificator/CameraModel were plain literals, so they did not link
into the API docs. Convert them to :meth:/:class: cross-references that
resolve against the autodoc'd ncore.data and ncore.sensors modules.

Apply the same treatment across the docs: convert the remaining bold
pseudo-headings to real headings with a consistent sub-hierarchy --
camera/lidar model names and external-distortion model names become
subsection headings (so the cross-referenced :ref: targets resolve to
real titled sections and show up in the page TOC), and their inline
'Mathematical Model', 'Parameters', 'Notation', 'Direction' labels
become nested sub-subsection headings. Likewise for the option/label
blocks in formats.rst, storage_and_access.rst and ncore_sequence_meta.rst.
@janickm janickm force-pushed the dev/janickm/fix-from-source-docs branch from 46de35f to 762aeda Compare June 17, 2026 13:49
@janickm janickm changed the title docs(sensor_models): fix from_source rendering and add API links docs: fix from_source rendering and promote bold pseudo-headings Jun 17, 2026
@janickm janickm added this pull request to the merge queue Jun 17, 2026
Merged via the queue into NVIDIA:main with commit e8cafba Jun 17, 2026
5 checks passed
@janickm janickm deleted the dev/janickm/fix-from-source-docs branch June 17, 2026 14:08
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