docs: fix from_source rendering and promote bold pseudo-headings#155
Merged
Merged
Conversation
7cf1a31 to
46de35f
Compare
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.
46de35f to
762aeda
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_sourcerendering and API links (the original report)(
**...**) as pseudo-headings. With a code literal inside the bold theyrendered oddly and never showed up in the page table of contents. Promoted
both to real RST subsection headings.
IdealPinholeCameraModelParameters.from_source/natural_fovand
Rectificator/CameraModelwere plain double-backtick literals, so theydid not link into the API docs. Converted them to
:meth:/:class:cross-references that resolve against the autodoc'd
ncore.dataandncore.sensorsmodules.Bold pseudo-headings promoted to a real sub-hierarchy
The same
**...**pseudo-heading pattern was used throughout the docs. Promotedthe 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 thatpoint at them now resolve to real titled sections (with permalink anchors) and
appear in the page TOC. Their inline
Mathematical Model/Parameters/Notation/Directionlabels become nested sub-subsection headings.docs/data/formats.rst:Label Type System/Encoding/Instance naming convention/Compat layer accessbecome sub-subsections of"Camera Labels Component".
docs/tools/ncore_sequence_meta.rst:Global options/V4 sub-command optionsbecome subsections of "Options".docs/data/storage_and_access.rst:Tradeoffsbecomes a subsection of the".itar" format section.
Mid-paragraph emphasis (e.g.
**Example:**,**Forward distortion**) is left asbold inline text, since those are not standalone headings.
Verification
bazel build //docs:ncoresucceeds with no RST or cross-reference warnings (onlypre-existing unrelated nbsphinx deprecation notices). The rendered HTML confirms:
data/sensor_models.html: model names render as<h3>and their inline labelsas nested
<h4>;:ref:links resolve to real heading anchors (e.g.#ftheta-camera-model); and thefrom_source/natural_fovreferences linkinto
apis/data.html#ncore.data.IdealPinholeCameraModelParameters.from_source(and
.natural_fov).data/formats.html,tools/ncore_sequence_meta.htmlanddata/storage_and_access.htmlshow the promoted headings at the expectednesting levels.