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.22%   84.22%           
=======================================
  Files         128      128           
  Lines        3322     3322           
  Branches      564      564           
=======================================
  Hits         2798     2798           
  Misses        324      324           
  Partials      200      200           

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

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

---

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 27ac10e...4dc2b20. 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.

[greenc-FNAL]

@copilot Does any of the documentation provided need to be updated due to changes in the code, or are there any new classes/files that would have been covered by the goals of the original prompt?

[Copilot]

@copilot Does any of the documentation provided need to be updated due to changes in the code, or are there any new classes/files that would have been covered by the goals of the ori...

All currently documented classes remain accurate. Two new user-facing classes were added to the codebase after the original branch was created and are now covered:

• phlex::experimental::module_graph_proxy (phlex/module.hpp) — the restricted graph_proxy subinterface users implement for algorithm modules, registering with PHLEX_REGISTER_ALGORITHMS
• phlex::experimental::source_graph_proxy (phlex/source.hpp) — the restricted subinterface for data sources, registering with PHLEX_REGISTER_PROVIDERS

Both are now documented in 31b7611.

[Copilot]

Pull request overview

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

[Copilot]

INPUT and OUTPUT_DIRECTORY are written as relative paths that only work if Doxygen is invoked from docs/ (e.g., cd docs && doxygen Doxyfile). If someone runs doxygen docs/Doxyfile from the repo root (a common invocation), ../phlex/../form will point outside the repo and the XML will be written to <repo>/doxygen/, which won’t match the Sphinx Breathe path or the .gitignore entries. Consider making these paths robust to the invocation working directory (e.g., repo-root-relative paths) or add a documented wrapper/Makefile target that enforces running from docs/.

Suggested change

	INPUT = ../phlex ../form
	OUTPUT_DIRECTORY = doxygen
	# Paths are relative to the repository root; invoke as: doxygen docs/Doxyfile
	INPUT = phlex form
	OUTPUT_DIRECTORY = docs/doxygen

[Copilot]

breathe_projects["Phlex"] points to ../doxygen/xml/ relative to docs/source/, which assumes Doxygen writes XML to docs/doxygen/xml. With the current docs/Doxyfile, that location depends on the working directory used when invoking Doxygen, so Sphinx can easily fail to find the XML. Align this path with a Doxygen output location that’s stable (or document/enforce the expected invocation directory).

[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.

[Copilot]

There appears to be an extra blank line at EOF in this newly added file. Repo text-file formatting guidelines require the file to end with exactly one newline and no trailing blank line; remove the final empty line.

[Copilot]

There appears to be an extra blank line at EOF in this newly added file (after breathe_default_project). Repo text-file formatting guidelines require the file to end with exactly one newline and no trailing blank line; remove the final empty line.

[Copilot]

There appears to be an extra blank line at EOF in this newly added file. Repo text-file formatting guidelines require the file to end with exactly one newline and no trailing blank line; remove the final empty line.

[Copilot]

There appears to be an extra blank line at EOF in this newly added file. Repo text-file formatting guidelines require the file to end with exactly one newline and no trailing blank line; remove the final empty line (and apply the same fix to the other new docs/source/api/*.rst files).

[Copilot]

templates_path = ["_templates"] points to a directory that is not present under docs/source/. Either add docs/source/_templates/ (if you intend to customize templates) or remove this setting to avoid Sphinx warnings about missing template directories.

[Copilot]

There appears to be an extra blank line at EOF in this newly added file (after the PREDEFINED block). Repo text-file formatting guidelines require the file to end with exactly one newline and no trailing blank line; remove the final empty line.