Add docs content and ensure all exported items have docstrings

[kdayday]

New export: combine_categories, part of the old PA workflow used by PowerGraphics. Not currently hyperlinking it from PG, and assuming it's about to be deleted anyways as part of PG rework. But if that doesn't happen, it'll be available to link

Major documentation improvements:

New guides and explanations:

• Added new "How to..." guides on grouping generation by fuel/technology (how_to_group_generation_by_fuel.md) and defining custom metrics (how_to_define_a_custom_metric.md), providing step-by-step instructions and code examples. [1] [2]
• Introduced in-depth explanation pages: "How PowerAnalytics thinks" (metrics and selectors mental model) and "Choosing built-in metrics" (comparison and caveats for built-ins). [1] [2]

Navigation and structure:

• Updated the documentation navigation (make.jl) to include the new "How to..." and "Explanation" sections, replacing previous TODOs.
• Removed obsolete stub pages for how-to and explanation sections. [1] [2]

General documentation cleanup and enhancements:

Improved references and cross-linking:

• Updated cross-references to use @ref and @extref for easier navigation, including in the main index, developer guidelines, and tutorial. [1] [2] [3] [4] [5] [6]
• Clarified language around the use of ComponentSelector and its documentation. [1] [2]

Minor content and formatting fixes:

• Fixed line breaks, clarified version support, and corrected minor typos in the index and Sienna ecosystem overview. [1] [2]

[Copilot]

Pull request overview

This PR expands and restructures the package documentation while tightening docstring coverage for exported APIs, and it exposes combine_categories as a public export to support legacy workflows.

Changes:

• Exported combine_categories and added/expanded docstrings across result-extraction and metric utilities.
• Added new “How to…” guides and “Explanation” pages, and updated docs navigation to include them.
• Cleaned up documentation cross-linking (moving toward @ref / @extref) and removed obsolete stub pages.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/PowerAnalytics.jl	Exports combine_categories (and keeps exports aligned with documented public surface).
src/metrics.jl	Adds docstrings for exported metric accessor functions (e.g., get_name, get_time_agg_fn).
src/get_data.jl	Adds/expands docstrings for PowerData, data extractors, and category utilities (no_datetime, combine_categories, categorize_data).
src/fuel_results.jl	Clarifies make_fuel_dictionary docstrings and adds docstring for the default-mapping method.
src/builtin_metrics.jl	Replaces short string docs with richer docstrings for several built-in metrics (formulas/caveats).
docs/src/tutorials/PA_workflow_tutorial.jl	Updates external/internal links to use @ref / @extref rather than raw URLs.
docs/src/reference/public.md	Updates ComponentSelector references and keeps API reference structure intact.
docs/src/reference/developer_guidelines.md	Converts external doc links to @extref doc links.
docs/src/index.md	Updates overview wording, cleans up formatting/typos, and adjusts version wording to “5.x”.
docs/src/how_to_guides/stub.md	Removes obsolete placeholder stub page.
docs/src/how_to_guides/how_to_group_generation_by_fuel.md	Adds a new how-to guide for category-based grouping using built-in selectors/mappings.
docs/src/how_to_guides/how_to_define_a_custom_metric.md	Adds a new how-to guide for composing/rebuilding/defining custom metrics.
docs/src/explanation/stub.md	Removes obsolete placeholder stub page.
docs/src/explanation/metrics_and_component_selectors.md	Adds a conceptual explanation of metrics/selectors and aggregation behavior.
docs/src/explanation/choosing_built_in_metrics.md	Adds guidance on selecting among built-in metrics and interpreting caveats.
docs/make.jl	Adds the new pages to the navigation structure under “How to…” and “Explanation”.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.94%. Comparing base (50b9902) to head (91cc72a).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #79   +/-   ##
=======================================
  Coverage   87.94%   87.94%           
=======================================
  Files           7        7           
  Lines         763      763           
=======================================
  Hits          671      671           
  Misses         92       92           

Flag	Coverage Δ
unittests	87.94% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.