Skip to content

Docs: per-topic directories + sphinx_reredirects - #60

Merged
mmmarinho merged 1 commit into
mainfrom
docs-topic-directories
Oct 28, 2026
Merged

mmmarinho merged 1 commit into
mainfrom
docs-topic-directories

Conversation

@mmmarinho

Copy link
Copy Markdown
Owner

The reorganisation

The three newest sections already use one directory per toctree caption (transformations/, gazebo/, navigation/, plus cybersecurity/ cpp/ sas/ docker/ cmake/). This brings the remaining 24 flat pages into the same shape:

caption directory pages
ROS2 Setup setup/ installation, terminator, workspace_setup
ROS2 Python Package/Build packages/ create_packages, create_python_package, create_python_node_with_template, source_after_build, running_node
ROS2 Python Node python_node/ create_python_node_from_scratch, python_node_explained
ROS2 Python Library python_library/ create_python_library, using_python_library
ROS2 Interfaces interfaces/ interfaces, create_interface_package
ROS2 Messages messages/ publishers_and_subscribers, inspecting_topics
ROS2 Parameter/Launch parameters_and_launch/ parameters_and_launch, launch_configurable_nodes, inspecting_parameters
ROS2 Services services/ service_servers_and_clients, inspecting_services
ROS2 Actions actions/ actions, action_servers, action_clients

index.rst, tools.rst, faq.rst and the two included snippets (the_canonical_build_command, the_topic_is_under_heavy_construction) stay at the source root — the snippets are included from every depth and ../the_... from one dir down is already the established pattern.

All moves are git mv (history preserved). Path rewrites: literalinclude/:download:, snippet include::, terminator images, the root toctree and :doc: quick-start links, and the cross-refs in tools.rst/sas/index.rst. :ref: labels are path-independent.

Keeping the old URLs alive

sphinx_reredirects (1.1.0) hooks html-collect-pages, so the meta-refresh stubs for all 24 old locations (.../en/latest/installation.html etc.) are generated by the regular html build — no extra builder invocation or RTD job. (The 0.1.x-era -b redirects recipe would actually break the RTD build, since 1.1 dropped that builder.)

Verification

  • fresh sphinx-build -b html locally: build succeeded, warning set identical to before the move (mermaid/mmdc-absent locally, one upstream 404, pre-existing title/markup warnings) — no broken references, no orphan documents
  • all 24 redirect stubs verified present in the built tree, e.g. installation.html -> setup/installation
  • new pages verified rendered (setup/installation.html, actions/action_clients.html)

Mirrors the transformations/gazebo/navigation (and cybersecurity/cpp/
sas/docker/cmake) layout for the remaining 24 flat pages, one directory
per toctree caption:

- setup/: installation, terminator, workspace_setup
- packages/: create_packages, create_python_package,
  create_python_node_with_template, source_after_build, running_node
- python_node/: create_python_node_from_scratch, python_node_explained
- python_library/: create_python_library, using_python_library
- interfaces/: interfaces, create_interface_package
- messages/: publishers_and_subscribers, inspecting_topics
- parameters_and_launch/: parameters_and_launch,
  launch_configurable_nodes, inspecting_parameters
- services/: service_servers_and_clients, inspecting_services
- actions/: actions, action_servers, action_clients

index.rst, tools.rst, faq.rst and the two included snippets
(the_canonical_build_command, the_topic_is_under_heavy_construction)
stay at the source root -- the snippets are included from every depth
and the ../the_... convention of the existing topic dirs applies.

Relative paths (literalinclude/:download: ../.. -> ../../.., snippet
includes -> ../, terminator images) and the cross-references from
tools.rst and sas/index.rst were rewritten; :ref: labels are
path-independent. A full local sphinx html build reproduces the exact
pre-existing warning set (mermaid/mmdc-absent, upstream 404, title
underlines) with no broken references.
@mmmarinho
mmmarinho merged commit bd16622 into main Oct 28, 2026
6 checks passed
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