Skip to content
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

Autogenerate API documentation #3378

Merged
merged 82 commits into from
Oct 11, 2024
Merged

Autogenerate API documentation #3378

merged 82 commits into from
Oct 11, 2024

Conversation

jsiirola
Copy link
Member

@jsiirola jsiirola commented Oct 4, 2024

Fixes # .

Summary/Motivation:

This PR is primarily adds the automatic generation of the API documentation for the entire Pyomo codebase to the Sphinx build.

This also silences all Sphinx warnings that were being generated

Changes proposed in this PR:

  • Add the API documentation under Reference / Library Reference
  • Move the old library reference to Reference / Topical Reference
  • Switch to using BiBTeX alpha format for all references (that are not references to Pyomo publications)
  • Consolidated references into the bibliography
  • Remove the (unused) Sphinx intersphinx reference
  • Remove the use of sphinx.ext.autosectionlabel
  • Restored the working with abstract models" docs
  • Extensive updates to docstrings to resolve Sphinx warnings
  • Pyomo code
    • cleaned ConfigDict numpydoc generation (improve references, resolve sphinx warnings)
    • Add an IntEnum wrapper to rewrite some docstrings to silence Sphinx warnings
    • remove use of "bare" absolute imports in Pyomo __init__.py files (resolves Sphinx autosummary issue)
    • Prevent importing Qt when building docs
    • Switch from docstrings to decorators for defining PLY grammars

Legal Acknowledgement

By contributing to this software project, I have read the contribution guide and agree to the following terms and conditions for my contribution:

  1. I agree my contributions are submitted under the BSD license.
  2. I represent I am authorized to make the contributions and grant the license. If my employer has rights to intellectual property that includes these contributions, I represent that I have received permission to make contributions and grant the required license on behalf of that employer.

(This normalizes the doc strings to avoid indention warnings from Sphinx)
@jsiirola jsiirola requested a review from mrmundt October 9, 2024 19:08
model.o = pyo.Objective(expr=model.v1 + model.v2)
solver = pyo.SolverFactory('glpk')
input_vars = [model.v1]
n_scen = 2
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not relevant for this PR but marking for posterity - what is n_scen?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe "number of scenarios"

Copy link
Contributor

@mrmundt mrmundt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes yes, I am pleased.

@jsiirola jsiirola merged commit c157587 into Pyomo:doc-reorg Oct 11, 2024
1 check passed
@jsiirola jsiirola deleted the doc-index branch October 11, 2024 13:36
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.

2 participants