Documentation review 2#140
Merged
Merged
Conversation
The weather.md example used the pre-MIT-LAE#138 `Weather('path', mission, track)` signature, which no longer exists. Rewrite to use the current constructor `Weather(data_dir, file_resolution=TemporalResolution.DAILY)`, the matching `GroundTrack.great_circle(Location, Location)` call, and the current `get_ground_speed(time, gt_point, altitude, true_airspeed)` signature. Marks Critical MIT-LAE#1 in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The performance_model_files.md example TOML used `cas_lo` / `cas_hi` in all three `[speeds.*]` blocks, but pydantic validation rejects these — the canonical field names emitted by `make-performance-model` and accepted by `LegacyPerformanceModel` are `cas_low` / `cas_high` (see `sample_performance_model.toml:23-36`). Rename in the example so it loads. Marks Critical MIT-LAE#2 in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Under `[LTO_performance]`, the example TOML used `Foo_kN = 102.695` — a leftover from the BADA OPF source format that was never the actual field on `LegacyPerformanceModel`. The real (and only accepted) key is `rated_thrust`, as emitted by `make-performance-model` and shown in `sample_performance_model.toml:46`. Marks Critical MIT-LAE#3 in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
PR MIT-LAE#135 changed the layout emitted by `make-performance-model legacy` (and accepted by `LegacyPerformanceModel`) from a single `[flight_performance]` table to three per-phase tables: `[climb_flight_performance]`, `[cruise_flight_performance]`, and `[descent_flight_performance]`, each with the same 5-column schema (`fuel_flow, fl, tas, rocd, mass`). The example in `performance_model_files.md` still showed the old single-table format with 6-column rows, which would now fail validation. Replace the example block with three per-phase tables and a few representative rows pulled from `sample_performance_model.toml`. Marks Critical MIT-LAE#4 in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
`aeic make-performance-model legacy` declares `--maximum-payload` as required (see `make_performance_model.py:324-329`), so the example in `performance_model_files.md` exited with "Missing option '--maximum-payload'" before doing any work. Add the flag to the example using the value from the sample model (22422 kg). Marks Critical MIT-LAE#5 in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Step 8 of the workflow in `emission.md` cross-referenced `<AEIC.emissions.types.Emissions>`, but no `AEIC.emissions.types` module exists. The class lives at `AEIC.emissions.emission.Emissions` and is re-exported as `AEIC.emissions.Emissions` via `__all__`. Point the xref at the re-exported path so Sphinx resolves the link. Marks Critical MIT-LAE#6 in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…ntics The prose said `valid_time` is "sliced using `mission.departure.hour` if present", but PR MIT-LAE#138 replaced that with `xarray.Dataset.sel(time, method='nearest', tolerance=1h)` whenever `data_resolution` is finer than `file_resolution`. When the two match, `valid_time` is absent or length-1 and no slicing happens at all. Update the bullet to describe the current behaviour. Marks Major MIT-LAE#7 in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
PR MIT-LAE#138 added public symbols `TemporalResolution`, `default_file_format`, and `resolution_le` to `AEIC.config.weather`, plus three new fields on `WeatherConfig` (`file_resolution`, `data_resolution`, `file_format`). None of these appeared in `configuration.md`. Add a prose preamble to the Weather configuration section that explains the file/data resolution coupling and the strftime-token rules per file resolution, plus autoenum and autofunction directives for the three new public symbols. Marks Major MIT-LAE#8 in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The docstring for `Builder.fly` documented its third argument as `startMass`, a camelCase leftover from the AEIC v1 codebase. The actual parameter is `starting_mass` (snake_case, matching the project convention). autodoc renders the docstring verbatim into `trajectory_builders.md`, so users saw a kwarg name that wouldn't work. Marks Major MIT-LAE#9 in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
PR MIT-LAE#134 added `TimeRangeQuery` to `AEIC.missions.__all__`, but `mission_database.md` never mentioned it: the "main classes of interest" list omitted it and the queries overview claimed "three flavors". Add `TimeRangeQuery` to the class list, update the prose to "four flavors", and add a Time-range queries subsection with a usage example and an autoclass directive matching the pattern used for `CountQuery`. Marks Major MIT-LAE#10 in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
After PR MIT-LAE#134, `QueryResult.from_row` returns a plain `Mission(...)` rather than `cls(...)`, so `db(query)` actually yields `Mission` instances. Update `mission_database.md` to say so: change the result prose, drop the `QueryResult` bullet from the main-classes list (it is an internal database-driver helper, not part of the user-facing API), and remove the trailing `autoclass:: ...QueryResult` directive. Marks the `QueryResult` Major finding in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
`Builder`, `Options`, and `Context` all carry attribute-level docstrings now (see `base.py:18-71`), and the autoclass directive lower in the same page renders a usable reference. Replace the legacy "documentation is sparse" paragraph with one that points readers at the rendered reference and at `LegacyBuilder` as the working example. Marks the obsolete-Builder-prose Major finding in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The warning block in trajectory_builders.md complained that trajectories had to be sized up-front. This was fixed in 6c9f0d5 ("Extensible trajectories"); `Trajectory` now supports `append` / `fix`. Drop the obsolete language but keep the still-accurate note that there are no built-in helpers for the "extra" LTO flight phases. Marks the extensible-trajectories warning Major finding in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The `*Options` companions for the WIP builders (`TASOPTOptions`, `ADSBOptions`, `DymosOptions`) are exported from `AEIC.trajectories.builders` but were unmentioned in the WIP sections of `trajectory_builders.md`. Add a section-level note flagging that each builder has a matching options class whose fields will change, and cross-reference the relevant options class in each per-builder subsection. Update the per-builder warnings to make clear that both the builder and its options class are stubs. Marks the WIP-Options Major finding in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
PR MIT-LAE#139 added an optional `label: str = ''` argument to `EI_HCCO`, used to tag the calibration-failure warning at hcco.py:41. The Numpydoc Parameters block wasn't updated, so autodoc'd output (via `emission.md:162`) silently dropped the new parameter. Add an entry for `label` describing it as an optional engine/aircraft tag. Marks the EI_HCCO label Minor finding in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
`emission.md` mixed two xref styles for the same class: `AEIC.emissions.Emissions` (re-exported via __all__) and `AEIC.emissions.emission.Emissions` (deep path). Settle on the shorter re-export form for both the prose xref at line 113 and the autoclass directive that follows it. Marks the Minor xref-style finding in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
`oag.md` used a bullet list for `aeic convert-oag-data` options, while `cli.md` uses four-column option tables for the other subcommands. Replace the bullets with a matching table so CLI reference style is consistent across pages. Marks the Minor oag.md option-bullets finding in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The CLI subcommand table mixes inline `[below]` links and links to topic pages (oag.md, performance_model_files.md, gridding.md), which surprises readers expecting consistent placement. Add a `note` block right after the table calling out which three commands are documented inline and which three have flag tables on their topic pages. Marks the Minor cli.md table-style finding in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The `track_file_accesses` context manager is meant to wrap an entire `aeic run` invocation, not to be entered per-trajectory in interactive code. Without that hint, the symbol shows up in the storage `__all__` list with no usage guidance. Add a short `note` block in `storage.md` that says where it gets used and discourages per-trajectory usage. Marks the Minor storage.md callout finding in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The WeatherConfig autoclass directive in `configuration.md` uses bare `:members:`. Verify that the two properties added in PR MIT-LAE#138 (`effective_data_resolution`, `effective_file_format`) appear in the rendered output under the WeatherConfig reference. They do — bare `:members:` picks up `@property`-decorated attributes — so no source change is required. Mark the finding DONE. Marks the Minor WeatherConfig effective_* finding in documentation-review-2.md as DONE. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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
1 participant
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.
Second round of documentation fixes to bring things up to date. All clanker work again.