OpenMDAO / OpenMDAO/Aviary

Silent doc failures not being detected

Open
#649 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
Python
Stars
287
Forks
140
Avg merge
6d 14h
Merged PRs (30d)
18

Description

Desired documentation content.

Building the docs currently only checks for complete failures and errors, however there are issues that can occur that do not cause the cell to completely fail, but can produce the wrong answer. A current example of this is additional_flight_phases.ipynb, where a number of runtime warnings pop up. This is both concerning for a user reading the docs who doesn't know if these warnings are serious or not, and could lead to a doc showing the incorrect answer for an example.

We need to start baking asserts and other checks similar to our unittests and benchmark tests into doc cells (probably separate hidden cells) so we immediately know if something changed

Is there any existing documentation on your requested topic? Please describe.

No response

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the documentation build and inspecting additional_flight_phases.ipynb, especially the cells that emit runtime warnings. Read the existing unittest and benchmark-test patterns mentioned in the issue to understand how checks are structured. Done means documentation examples detect incorrect or warning-producing results rather than silently passing.

Written by the indexing model from the issue text.

Assessment

Tech stack
jupyter-notebook, python
Domain
documentation, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.