Skip to content

Improve documentation of algorithm options #554

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 17 commits into from
Jul 27, 2025
Merged

Conversation

janosg
Copy link
Member

@janosg janosg commented Nov 30, 2024

In this PR, we improve the documentation of algorithm options. Primarily, we:

  1. Use a modern sphinx version and remove deprecated sphinx extensions from the RTD environment
  2. Now only call .. autoclass:: optimagic.optimizers... without adding any description that is not in the code itself (except for a small how-to guide for using the algorithm)
  3. We give an example of how optimagic's algorithm classes need to be documented internally such that they are rendered nicely with sphinx
  4. We extend the mini "how-to" guide present for each optimizer on how to use this algorithm for minimization. The idea is that it could be very confusing to see that the class is called, e.g., ScipyLBFGSB, but that you are supposed to call it differently. To circumvent any confusion and user-frustration, two mini code-snippets show the user how to call each algorithm.
  5. We add a typing page to the documentation which documents all objects in the optimagic.typing module
  6. We fix some wrong indentations in the pounders docs
  7. Add guide on how-to document optimizers to the documentation

Copy link

codecov bot commented Nov 30, 2024

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines Coverage Δ
src/optimagic/optimizers/_pounders/bntr.py 86.71% <ø> (ø)
...timagic/optimizers/_pounders/pounders_auxiliary.py 97.32% <ø> (ø)
src/optimagic/optimizers/pounders.py 92.56% <ø> (ø)
src/optimagic/optimizers/scipy_optimizers.py 96.96% <100.00%> (+0.05%) ⬆️
src/optimagic/typing.py 88.50% <100.00%> (+1.66%) ⬆️
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@janosg janosg mentioned this pull request Jun 12, 2025
14 tasks
@janosg janosg requested a review from mpetrosian July 27, 2025 14:20
@janosg janosg merged commit 468b762 into main Jul 27, 2025
27 checks passed
@janosg janosg deleted the algorithm-docstrings branch July 27, 2025 14:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants