docs: gallery, keywords page, and API docstrings - #143
Open
kdayday wants to merge 11 commits into
Open
Conversation
kdayday
changed the title
There was a problem hiding this comment.
Pull request overview
Adds and reorganizes documentation for PowerGraphics, including a new gallery of plot archetypes, a shared plot-keywords reference, and refreshed docstrings across the public plotting/reporting API to improve discoverability and reduce Documenter warnings.
Changes:
- Added a docs “Gallery” page with CSS tiles and a Julia script to regenerate committed PNG examples.
- Introduced a “Plot styling keywords” reference and expanded/renamed the backends/how-to docs; removed the empty tutorials examples stub.
- Standardized/expanded docstrings across core API entry points and added DocStringExtensions templates for typed signatures.
Reviewed changes
Copilot reviewed 13 out of 22 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| src/PowerGraphics.jl | Adds DocStringExtensions template and documents report in the main module. |
| src/label_utils.jl | Refreshes label helper docstrings and links to the new plot-keywords reference. |
| src/definitions.jl | Updates load_palette docstring and cross-references related docs. |
| src/call_plots.jl | Overhauls plot function docstrings (arguments/keywords/see-also) for demand/dataframe/powerdata/results/fuel/save. |
| Project.toml | Adds DocStringExtensions dependency and compat entry. |
| ext/WeaveExt.jl | Removes redundant report docstring from the extension (now documented in the main module). |
| docs/src/tutorials/examples.md | Removes empty/stub examples page. |
| docs/src/reference/plot_keywords.md | Adds a central reference page for shared plot styling keywords. |
| docs/src/index.md | Expands the docs landing page overview and navigation guidance. |
| docs/src/how_to_guides/backends.md | Expands backend selection/saving/report guidance and updates page title/id. |
| docs/src/gallery/index.md | Adds the new gallery page with image tiles and links into the API reference. |
| docs/src/assets/gallery.css | Adds CSS styling for the gallery grid/cards. |
| docs/make.jl | Adds PowerAnalytics interlinks, updates nav structure, and registers the gallery CSS asset. |
| docs/gallery/generate_gallery.jl | Adds a script to regenerate committed gallery PNG assets from reproducible simulations/data. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
… example Force prettyurls and extensionless gallery API links so deployed docs match local builds; split load_palette docstrings by method; align report example names. Co-authored-by: Cursor <cursoragent@cursor.com>
Local file:// builds use public.html; CI prettyurls use public/; gallery cards no longer hardcode layout-sensitive API hrefs. Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 15 out of 24 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
docs/src/index.md:32
- This sentence claims NREL was formerly known as the “National Laboratory of the Rockies”, which is inaccurate and likely to confuse readers. The previous wording (“National Renewable Energy Laboratory (NREL)”) is the correct expansion.
`PowerGraphics.jl` is part of the National Laboratory of the Rockies (formerly known as NREL)'s
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
View: https://sienna-platform.github.io/PowerGraphics.jl/previews/PR143/
Summary
Add a Reference Gallery of committed plot archetypes (demand, fuel, powerdata line/stack/stair/bar, dataframe) with API links, CSS layout, and
docs/gallery/generate_gallery.jlto regenerate PNGs (closes Add a gallery in the docs #120).Expand how-to/backends and welcome pages; add a dedicated Plot styling keywords reference; drop the empty Tutorials/examples stub from
docs/make.jl.Overhaul exported API docstrings (
TYPEDSIGNATURESvia DocStringExtensions) acrosscall_plots.jl,label_utils.jl,definitions.jl, andreport; keep Old PowerAnalytics symbols as bare code (no@extref) so docs build withoutwarnonly.regenerate gallery with
julia --project=test docs/gallery/generate_gallery.jlNeeds to be followed by #142 after version update for PA