Skip to content

Cut explanation out of the API reference pages #514

Description

@felipebogaertsm

Ten of the 24 pages under docs/api/ carry design rationale, engine-cycle theory, derived equations and field-convention comparisons — content a reader wants away from the code, sitting where a reader is looking something up. Move each of the following to the explanation quadrant and leave the reference page with a one-line orientation and a link.

  • models/feed_systems.md — the three rationale paragraphs under "The FeedSystem contract": why every line is solved in one call, why keying by name leaves the propellant count free, and the split of responsibility with the injector. Goes to Explain how feed systems are modeled #504.
  • models/feed_systems/components.md — the "When you need which spec" table (its "Why" column is engine-cycle theory), the Sutton and Huzel bibliography, the pump shaft-power and turbine specific-work equations, the off-stoichiometric gas-generator rationale, and the note on why heat pickup and coolant temperature rise are both stored. Goes to Explain how feed systems are modeled #504.
  • models/feed_systems/cycles.md — the composition diagram, the roadmap paragraph on cycles under development, the single-phase incompressible and homogeneous-equilibrium flow equations with the nitrous oxide flashing rationale, and the note that feedline drop is stated rather than computed. Goes to Explain how feed systems are modeled #504.
  • models/feed_systems/tank.md — why the tank carries no state, and why a draining tank cools. Goes to Explain how feed systems are modeled #504.
  • models/thrust_chamber.md — the "Center Of Gravity Frames" section, which is a convention spanning the grain, the thrust chamber and the RocketPy adapter and needs its own explanation page; and the injector bullets restating the feed-system split already covered above.
  • simulation.md — the three bullets after the termination table: the vacuum case, the peak-pressure threshold at which tail-off fires first, and the impulse cost with the openMotor, NFPA 1125 and JANNAF comparison. Needs an explanation page on the simulation loop, which is also where Time marching is globally first order despite the fourth-order Runge-Kutta sub-step #483 belongs.
  • core/solvers.md — the reasoning for why a pressure-dependent source term must be a callable. Same destination as above; the contract itself stays.
  • core/mass_balance.md — the Seidel citation and the stage-consistency clause, already derived in full on the mass balance page. Replace with a link.
  • models/grain/fmm.md — the comparison against re-meshing at every regression step, already covered by the grain regression page. Replace with a link.
  • core/interpolation.md — the two numbered rationale points on smooth derivatives and refusing to extrapolate. No explanation page earns a section for one utility class; compress to a sentence in the class docstring.

Two defects found alongside:

adapters/rocketpy.md is a separate case: its installation section, four-step workflow and ninety-line example are a how-to guide on a reference URL. It needs the how-to quadrant, which does not exist yet, so it is out of scope here.

The 14 remaining pages are clean — core.md, models.md, models/grain.md and models/grain/geometries.md are the shape to hold the rest to.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions