Add Sphinx/Doxygen/Breathe documentation framework for phlex and phlex::experimental API

[Copilot]

Adds a Sphinx + Doxygen + Breathe documentation scaffold under docs/ to generate API reference documentation for phlex and phlex::experimental types, along with dependency requirements and gitignore entries for generated outputs.

Documentation framework

• docs/Doxyfile: Doxygen configuration for XML output consumed by Breathe; paths are repo-root-relative — invoke as doxygen docs/Doxyfile from the repository root
• docs/source/conf.py: Sphinx configuration with Breathe integration, version 0.1.0 matching CMakeLists.txt; breathe_projects path (../doxygen/xml/) resolves correctly to docs/doxygen/xml/ from docs/source/
• docs/source/index.rst: documentation index organized into three toctree sections: Plugin entry points, Algorithm nodes, Data model

Dependency pinning

• docs/requirements.txt: sphinx>=9.1,<10, breathe>=4.36,<5, sphinx-rtd-theme>=3.1,<4

API pages — phlex namespace

• phlex::configuration — parameter access class used by every algorithm
• phlex::handle<T> — data product access wrapper passed to algorithm functions
• phlex::concurrency — concurrency control struct used in algorithm registration

API pages — phlex::experimental namespace

• Plugin entry points: module_graph_proxy, source_graph_proxy, graph_proxy, framework_graph, registrar
• Algorithm nodes: declared_transform, declared_fold, declared_unfold
• Data model: product_store, products

Doxyfile configuration

• INPUT = phlex form, OUTPUT_DIRECTORY = docs/doxygen (repo-root-relative)
• FILE_PATTERNS = *.hpp *.cpp, EXCLUDE_PATTERNS = */detail/*
• PREDEFINED macros for current codebase (BOOST_DLL_ALIAS, PHLEX_DETAIL_REGISTER_PLUGIN)

Housekeeping

• .gitignore: added docs/doxygen/ and docs/build/ for generated output
• conf.py: module docstring added for ruff D100 compliance

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[greenc-FNAL]

@copilot I think for maximum clarity, it would be better to reset this branch to upstream/main and then re-do the work following the current philosophy, functions/class structure, etc.

[Copilot]

@copilot I think for maximum clarity, it would be better to reset this branch to upstream/main and then re-do the work following the current philosophy, functions/class structure, etc.

Done. In commit 412a5ec I reset the branch to main and removed all the stale files from the old base. In 0712ae9 I fixed the docs to match the current codebase (correct class names, macros, version).

The PR now shows only 13 files changed (135 additions, 0 deletions from main): the docs/ directory with Sphinx/Doxygen/Breathe configuration and API pages, plus .gitignore entries for docs build output.

[Copilot]

Pull request overview

Adds a Sphinx + Doxygen + Breathe documentation scaffold under docs/ to generate API reference documentation for key phlex::experimental types, along with dependency requirements and gitignore entries for generated outputs.

Changes:

• Add Sphinx project entrypoint (index.rst) and minimal conf.py wired to Breathe.
• Add API reference .rst pages for several phlex::experimental classes.
• Add Doxygen configuration + Python requirements, and ignore generated docs artifacts in .gitignore.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/source/index.rst	Adds top-level Sphinx landing page and toctree for API pages.
docs/source/conf.py	Adds Sphinx configuration with Breathe integration.
docs/source/api/graph_proxy.rst	Adds API page for phlex::experimental::graph_proxy.
docs/source/api/framework_graph.rst	Adds API page for framework_graph and layer_sentry.
docs/source/api/registrar.rst	Adds API page for phlex::experimental::registrar.
docs/source/api/declared_transform.rst	Adds API page for declared_transform.
docs/source/api/declared_fold.rst	Adds API page for declared_fold.
docs/source/api/declared_unfold.rst	Adds API page for declared_unfold.
docs/source/api/product_store.rst	Adds API page for product_store.
docs/source/api/products.rst	Adds API page for products.
docs/requirements.txt	Adds Python dependencies for building docs.
docs/Doxyfile	Adds Doxygen configuration to emit XML for Breathe.
.gitignore	Ignores generated Doxygen/Sphinx build output directories.

Comments suppressed due to low confidence (1)

docs/requirements.txt:4

• The PR description says dependencies are “pinned”, but requirements.txt uses version ranges (e.g., >=9.1,<10) which will allow new releases and can change doc build output over time. Either pin exact versions (e.g., ==...) to match the description, or update the description to reflect that these are minimum/compatible ranges. Also remove the trailing blank line at EOF to avoid generating a 4th empty requirement line.

sphinx>=9.1,<10
breathe>=4.36,<5
sphinx-rtd-theme>=3.1,<4

[greenc-FNAL]

@phlexbot python-fix

[github-actions]

Automatic ruff fixes pushed (commit af87c94).
⚠️ Note: Some issues may require manual review and fixing.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##             main     #323   +/-   ##
=======================================
  Coverage   84.94%   84.94%           
=======================================
  Files         127      127           
  Lines        3341     3341           
  Branches      574      574           
=======================================
  Hits         2838     2838           
  Misses        306      306           
  Partials      197      197           

Flag	Coverage Δ
unittests	84.94% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update aff8ec0...b4afc05. Read the comment docs.

🚀 New features to boost your workflow:

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

[greenc-FNAL]

@copilot This PR (branch copilot/update-branch-with-main-again) has been rebased against main once more: please re-evaluate and bring up to date with respect to the goals of your original prompt for this task.

[Copilot]

@copilot This PR (branch copilot/update-branch-with-main-again) has been rebased against main once more: please re-evaluate and bring up to date wi...

Re-evaluated after rebase. The only needed fix was removing the layer_sentry reference from framework_graph.rst — that class was deleted from the codebase since my last update. All other documented classes (graph_proxy, framework_graph, registrar, declared_transform, declared_fold, declared_unfold, product_store, products) verified present. Dependency versions, macros, and project version all still current. Done in 234e183.

[Copilot]

Pull request overview

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

[greenc-FNAL]

@copilot https://gh.io/copilot-coding-agent-docs #323 (branch copilot/update-branch-with-main-again) has been rebased against main once more: please re-evaluate and bring up to date with respect to the goals of your original prompt for this task. Please also extend the goals of the original prompt to cover the entire phlex namespace, not just phlex::experimental.

[Copilot]

@copilot https://gh.io/copilot-coding-agent-docs #323 (branch copilot/update-branch-with-main-again) has been rebased against main once...

Done in 958e762:

Doxyfile paths fixed: INPUT = phlex form and OUTPUT_DIRECTORY = docs/doxygen are now repo-root-relative; canonical invocation is doxygen docs/Doxyfile from the repo root. The Sphinx breathe_projects path (../doxygen/xml/ from docs/source/) already resolves correctly to docs/doxygen/xml/.

phlex namespace added: three new API pages covering the root namespace:

• phlex::configuration — parameter access for algorithms
• phlex::handle<T> — data product access wrapper passed to algorithm functions
• phlex::concurrency — concurrency control struct used in registration

index.rst reorganized into three toctree sections: Plugin entry points, Algorithm nodes, Data model.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 6 comments.

[greenc-FNAL]

Review the full CodeQL report for details.

[greenc-FNAL]

@copilot PR #323 (branch copilot/update-branch-with-main-again) has been rebased against main once more: please re-evaluate and bring up to date with respect to the goals of your original prompt for this task. Please ensure the documentation added by this PR remains accurate and up-to-date with respect to changes to main since the last rebase.

[Copilot]

@copilot PR #323 (branch copilot/update-branch-with-main-again) has been rebased against main once more: please re-evaluate and bring up to date with respect to the goals of your ori...

Re-evaluated after rebase. The only commit to main since the last rebase was workflow/action maintenance (#434) — no new public API classes were added. All 13 documented classes verified present (phlex::configuration, phlex::handle, phlex::concurrency, and 10 phlex::experimental types). Version, macros, and Doxyfile paths are still correct.

Also fixed the outstanding review issue: removed the nonexistent _templates path from conf.py to prevent Sphinx warnings (1722c43). Trailing-blank-line issues from the previous review were already resolved by the rebase.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 1 comment.