Docs that can build - #25
Conversation
The docs job has failed on every run since it was added: five runs, back to 2026-07-26, all red. `sphinx-build -W` turns four warnings into errors, and all four come from this fork's own additions rather than from upstream. Three are one stray line, copied three times. `add_thrust_vector_control`, `add_roll_control` and `add_throttle_control` describe the controller arguments as a numbered list, and item 7 ends with a loose ``interactive_objects`` at one space less than the continuation lines above it. docutils reads that as a definition list ending without a blank line. The same item in upstream's `add_air_brakes` does not have it, so removing it puts these three back in step with the method they were copied from. Measured per docstring, running napoleon and docutils the way Sphinx does. Before: those three warn at line 28, `add_air_brakes` does not. After: none of the four warn. The fourth is `halcyon_flight_sim_active_control.ipynb`, which is in `docs/examples/` and in no toctree, so Sphinx builds it and then reports that nothing links to it. It is this fork's own example of the feature the fork exists for, so it goes in the list next to the flight it varies rather than into an exclude. Not verified by a full local build: an unrelated notebook fetches a live weather forecast and the file it reaches no longer covers the date it asks for, which stops the build here for a reason CI does not have. Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>
`docs.yml` triggered on a base of master only, so the only pull request that ever started it was develop into master. A docstring that does not build therefore lands on develop unremarked and first fails the merge that was meant to ship it, which is what #19 and #23 hit and why the four warnings in the commit before this one went unnoticed for three days. develop as well. The same paths filter, so it still only runs when something it reads has changed. This also makes the commit before it self checking: without this, a pull request into develop cannot start the job that would prove the warnings are gone, and the only evidence would be a measurement in the description. Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>
|
Ready for review. Nine checks green, and the one that matters is That is only true because the trigger change is in the same PR. That trigger is also why nobody saw this for three days: the only run was the develop into master pull request, so a docstring that does not build lands on develop unremarked and first fails the merge that was meant to ship it. The four warnings are all this fork's own additions rather than upstream's, which is why they arrived with the job instead of being caught by it. Three are one stray line copied three times, traced with |
The docs job has failed on every run since it was added. Five runs, back to 2026-07-26, all red:
sphinx-build -Wturns warnings into errors and there are four. All four come from this fork's own additions, not from upstream, which is why they arrived with the job rather than being caught by it.Three of them are one stray line, copied three times
add_thrust_vector_control,add_roll_controlandadd_throttle_controldescribe the controller arguments as a numbered list. Item 7 ends with a looseinteractive_objectsat one space less than the continuation lines above it:docutils sees the indent go 19 -> 18 and reports a definition list ending without a blank line. The line carries no meaning where it is; upstream's
add_air_brakeshas the same item 7 and moves straight on to item 8.git log -Ltraces all three to 87e8f86, the RocketPy 1.12 merge, so they predate the job that reports them and did not come from #19.Removing them puts these three docstrings back in step with the method they were copied from, which is also the smaller divergence from upstream.
The fourth
docs/examples/halcyon_flight_sim_active_control.ipynbsits indocs/examples/and in no toctree, so Sphinx builds it and then reports that nothing links to it. It is this fork's own example of the feature the fork exists for, so it goes into the list next to the flight it varies rather than into an exclude pattern.Verified
Per docstring, running napoleon and docutils the way Sphinx does, against this branch and against
origin/develop:Same line number and same message as the job reports.
add_air_brakesis the control: it is upstream's, it is clean in both, and it stays clean.I could not finish a full local build to confirm the whole run goes green. An unrelated notebook fetches a live weather forecast and the file it reaches no longer covers the date it asks for, so the build stops here for a reason CI does not have.
And the job will not run on this pull request.
docs.ymltriggers onpull_requestwithbranches: [master]and on pushes to master, so a PR intodevelopnever starts it. That is also why this went unnoticed: the only runs are the ones a develop-to-master PR sets off, so a docs regression lands on develop and is first seen at the release merge, which is what happened with #19 and #23. Worth considering whether that trigger should includedevelop, but that is a separate change from the four warnings, so it is not in here.Concretely: green checks on this PR say nothing about the docs. The proof offered is the per-docstring measurement above.