Skip to content

Docs improvements - #452

Open
rgcoe wants to merge 21 commits into
sandialabs:devfrom
rgcoe:docs_april_2026
Open

Docs improvements#452
rgcoe wants to merge 21 commits into
sandialabs:devfrom
rgcoe:docs_april_2026

Conversation

@rgcoe

@rgcoe rgcoe commented Apr 17, 2026

Copy link
Copy Markdown
Contributor

Description

Clean up and improvements to documentation pages.

  • Add new papers and URLs for old papers to References
  • Transition references to Autograd -> Jax

TODO: not sure what this is, but maybe can be removed? https://github.com/rgcoe/WecOptTool/blob/8577c0ed17596ae47799c97c56077422f246f7ef/wecopttool/core.py#L80-L82

@rgcoe

rgcoe commented Apr 17, 2026

Copy link
Copy Markdown
Contributor Author

@dtgaebe - You could add your new animations to this PR if you like, but we (we = you and/or @jtgrasb) should first review/merge #451, as this PR take advantage of and is branched from #451.

@coveralls

coveralls commented Apr 17, 2026 •
edited
Loading

Copy link
Copy Markdown

Coverage Report for CI Build 29518756120

Coverage at 87.964% (no base build to compare)

Details

  • Coverage remained the same as the base build.
  • Patch coverage: 1 of 1 lines across 1 file are fully covered (100%).
  • No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

Coverage Stats

Coverage Status
Relevant Lines: 1429
Covered Lines: 1257
Line Coverage: 87.96%
Coverage Strength: 5.28 hits per line
💛 - Coveralls

@jtgrasb
jtgrasb self-requested a review May 14, 2026 21:13
dtgaebe added 8 commits June 18, 2026 11:20
@dtgaebe
Make local docs builds more robust on Windows
8766e05 
Improve the local documentation build workflow, especially on Windows.

- make docs example copying idempotent in docs/source/conf.py
- add an environment-variable option to skip theory animation generation
- add an environment-variable option to skip gifsicle optimization
- make docs/clean_docs.py report cleanup failures without aborting

These changes help local doc builds succeed when generated files are
reused between Sphinx phases or when optional tools like gifsicle are
not installed.
@dtgaebe
fixed broken jax link and indent of doc string
cdbd3ed
@dtgaebe
fix list docstring in plot_power_flow
a4ab4ef
@dtgaebe
PEP8 style for function signature
709fad8
@dtgaebe
Add pseudo-spectral theory visualization assets
e6ee9ec 
Add a script and generated static assets for illustrating the
time/frequency equivalence used by the pseudo-spectral method.

This includes:
- a static figure showing the relationship between Fourier coefficients,
  harmonics, collocation points, and the periodic time trajectory
- a WaveBot animation showing an actual pseudo-spectral solution iterate history
- a Python script that reproduces these documentation assets

The generated files are committed so documentation builds do not depend on
external optimization-history data or additional runtime generation steps.
@dtgaebe
static optimization data of electrical power optimization for Wavebot…
8130df1 
… tut1 with wot3p2p1
@dtgaebe
Integrate pseudo-spectral visualizations into theory docs
077d267 
Update the theory documentation to include the new
time/frequency equivalence discussion and WaveBot solution animation.

This commit also wires the visualization generation into the
documentation build configuration.
@dtgaebe
editorial changes
49ae266
@dtgaebe

dtgaebe commented Jun 18, 2026

Copy link
Copy Markdown
Collaborator

@rgcoe , @jtgrasb I finally added more description to the theory section with new figure and new solution animation.
I first had to change files to build the docs locally. It should make things more robust for windows. I hope I didn't break anything!

@dtgaebe
dtgaebe marked this pull request as ready for review June 22, 2026 17:20
@jtgrasb

jtgrasb commented Jul 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

@rgcoe @dtgaebe Overall, these changes look good, just a few clarifying points:

  • There are sections in the conf.py for both the theory and pseudospectral animations to check if the XXXX_generated variable is true. However, I don't see anywhere that sets the XXXX_generated variables to True or False. Not really an issue, just trying to understand if there is something else this is meant to do such as check if the .pngs are already present?
  • make_pseudospectral_visualizations is only imported, so the functions are never actually ran and no visualizations generated. This should be updated so the functions are called on import and the visualizations generated.
  • Assuming, the above points are fixed to always generate the figures, the png files can be moved to gitignore.

I can make the above change, just documenting to check in with the team before changing and merging PR.

@rgcoe

rgcoe commented Jul 16, 2026

Copy link
Copy Markdown
Contributor Author

Thanks very much @jtgrasb; I'd be very grateful if you can carry this over the finish line.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jtgrasb jtgrasb Awaiting requested review from jtgrasb

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@rgcoe @coveralls @dtgaebe @jtgrasb