Problem doc

[g-braeunlich]

Description

As a draft, the changes only have been applied to ThermoElastic2D.

• Move most parts of documentation to the corresponding md file
• Automatically read docstrings of Conditions and put it into the table
• Rename current directive to problem:table
• Add a new directive problem:conditions (inserting a list of conditions as found in the table)
• Both directives do not need the problem id anymore, it will be guessed by the markdown filename, but still can be overridden by a :problem_id: option
• The current doc tools are now described in docs/README.md and docs/tutorials/new_problem.md
• Add a directive option :lead: to the problem:table directive. This automatically creates a link to the github page. Example usage:

  ```{problem:table}
  :lead: Chuck Norris @chucknorris
  ```

  This will insert a link to https://github.com/chucknorris in the table

Type of change

Please delete options that are not relevant.

• Documentation only change (no code changed)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Checklist:

• I have run the pre-commit checks with pre-commit run --all-files
• I have run ruff check . and ruff format
• I have run mypy .
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Reviewer Checklist:

• The content of this PR brings value to the community. It is not too specific to a particular use case.
• The tests and checks pass (linting, formatting, type checking). For a new problem, double check the github actions workflow to ensure the problem is being tested.
• The documentation is updated.
• The code is understandable and commented. No large code blocks are left unexplained, no huge file. Can I read and understand the code easily?
• There is no merge conflict.
• The changes are not breaking the existing results (datasets, training curves, etc.). If they do, is there a good reason for it? And is the associated problem version bumped?
• For a new problem, has the dataset been generated with our slurm script so we can re-generate it if needed? (This also ensures that the problem is running on the HPC.)
• For bugfixes, it is a robust fix and not a hacky workaround.

[g-braeunlich]

@markfuge This is my draft. A generated artifact of the docs already exists here: https://github.com/IDEALLab/EngiBench/actions/runs/20821693995/artifacts/5064370177
Who else should we let review?

[g-braeunlich]

New docs (including the condition docstrings): https://github.com/IDEALLab/EngiBench/actions/runs/20962061394/artifacts/5113911870

[markfuge]

@g-braeunlich This in general looks good. We will check at the next EngiBench meeting whether we want to have the conditions also listed in the Markdown description and not just in the table, but pending that decision, we can merge it. I will approve for now and we can wait to officially merge after the next meeting decision

[g-braeunlich]

@markfuge I pushed a new version.

New changes:

• the current directive has been renamed to problem:table
• new directive is now problem:conditions
• both directives do not need the problem id anymore, it will be guessed by the markdown filename, but still can be overridden by a `:problem_id: option
• The current doc tools are now described in docs/README.md and docs/tutorials/new_problem.md

I still did not touch other problems than thermoelastic2d (except renaming the problem table directive).
Do we want to let the leads migrate the other problems, so they familiarize themselves with the new doc tools or do you want me to do that?

[markfuge]

@g-braeunlich took a look at the build artifact and in general this look good. Only aesthetic issue I see is that the table in the later Conditions heading is a bit verbose:

Would it be possible to automatically represent this more compactly, say without the typing information, kind of like we do with the current Airfoil docs:

[g-braeunlich]

It should now be a bullet point list without defaults / types

[markfuge]

@g-braeunlich This looks great now, thank you!

Do we want to let the leads migrate the other problems, so they familiarize themselves with the new doc tools or do you want me to do that?

If you could do this on behalf of the team, that would be great, but if any questions come up you could reach out to the individual leads. We can test the new instructions on the new problems being developed in the Spring (Aero3D and Beams3D)

[g-braeunlich]

Should be done now.
Notes:

• Also added some other fixes to the docs (invalid references, unincluded content)
• In your problem, you displayed default values -> added an option to the `problem:conditions: directive so you can enable default values

[markfuge]

@g-braeunlich I think this looks like a good pass at this for all problems. I think we can talk with individual leads about what modifications to individual problems would make the most sense for the problem specific documentation and they can handle this in a separate PR if needed, but as a general update to the way we handle the docs and conditions, I think this is good to merge now. Thanks for the heavy lifting on this!