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

[Copilot]

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.

Documentation framework

• docs/Doxyfile: Doxygen configuration for XML output consumed by Breathe
• docs/source/conf.py: Sphinx configuration with Breathe integration, version 0.1.0 matching CMakeLists.txt
• docs/source/index.rst: documentation index with toctree

Dependency pinning

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

API pages

• RST pages for module_graph_proxy, source_graph_proxy, graph_proxy, framework_graph, registrar, declared_transform, declared_fold, declared_unfold, product_store, products
• module_graph_proxy and source_graph_proxy are the primary user-facing plugin entry points (from phlex/module.hpp and phlex/source.hpp) for writing algorithm modules and data sources

Doxyfile configuration

• FILE_PATTERNS = *.hpp *.cpp, EXCLUDE_PATTERNS = */detail/*
• PREDEFINED macros updated 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   86.51%   86.47%   -0.05%     
==========================================
  Files         119      119              
  Lines        2403     2403              
  Branches      387      387              
==========================================
- Hits         2079     2078       -1     
- Misses        206      207       +1     
  Partials      118      118              

Flag	Coverage Δ
unittests	86.47% <ø> (-0.05%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 4 files 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 103c08c...3b11ebf. 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).