Add Sphinx/Doxygen/Breathe documentation framework for phlex and phlex::experimental API by Copilot · Pull Request #323 · Framework-R-D/phlex

Copilot · 2026-02-13T17:09:09Z

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 · 2026-02-13T18:03:02Z

@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 · 2026-02-13T18:10:33Z

@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

docs/source/conf.py

greenc-FNAL · 2026-02-13T21:05:26Z

@phlexbot python-fix

github-actions · 2026-02-13T21:06:02Z

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

codecov · 2026-02-13T21:15:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@            Coverage Diff             @@
##             main     #323      +/-   ##
==========================================
+ Coverage   84.05%   84.08%   +0.03%     
==========================================
  Files         127      127              
  Lines        3306     3306              
  Branches      562      562              
==========================================
+ Hits         2779     2780       +1     
  Misses        329      329              
+ Partials      198      197       -1

Flag	Coverage Δ
unittests	`84.08% <ø> (+0.03%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 3 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 4374590...8934e85. 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 · 2026-03-04T18:56:38Z

@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 · 2026-03-04T18:59:54Z

@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 · 2026-03-04T19:03:36Z

@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 · 2026-03-04T19:06:34Z

@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 · 2026-03-04T21:09:59Z

docs/Doxyfile

+INPUT             = ../phlex ../form
+OUTPUT_DIRECTORY  = doxygen


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 · 2026-03-04T21:09:59Z

docs/source/conf.py

+breathe_projects = {
+    "Phlex": "../doxygen/xml/",
+}


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 · 2026-03-09T17:29:16Z

@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 · 2026-03-09T17:33:20Z

@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 · 2026-03-09T18:36:10Z

docs/requirements.txt

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


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 · 2026-03-09T18:36:11Z

docs/source/conf.py

+breathe_projects = {
+    "Phlex": "../doxygen/xml/",
+}
+breathe_default_project = "Phlex"


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 · 2026-03-09T18:36:11Z

docs/source/index.rst

+   api/configuration
+   api/handle
+   api/concurrency
+   api/product_store
+   api/products


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 · 2026-03-09T18:36:11Z

docs/source/api/handle.rst

+.. doxygenclass:: phlex::handle
+   :members:
+   :undoc-members:


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 · 2026-03-09T18:36:12Z

docs/source/conf.py

+templates_path = ["_templates"]
+exclude_patterns = []


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 · 2026-03-09T18:36:12Z

docs/Doxyfile

+PREDEFINED        = "BOOST_DLL_ALIAS(a,b)=" \
+                    "PHLEX_DETAIL_REGISTER_PLUGIN(...)="


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.

greenc-FNAL · 2026-03-16T16:08:23Z

Review the full CodeQL report for details.

…work This commit introduces the foundational infrastructure for documenting the C++ codebase using a Sphinx, Doxygen, and Breathe toolchain. Key changes include: - A new `docs/` directory to house all documentation-related files. - Configuration files for Sphinx (`conf.py`) and Doxygen (`Doxyfile`). - A `requirements.txt` file listing the necessary Python dependencies for building the documentation. - The `phlex/core/graph_proxy.hpp` header has been fully documented with Doxygen comments to serve as a style guide and working example. - An initial Sphinx structure in `docs/source/` that integrates the Doxygen XML output via Breathe, making the `graph_proxy` documentation available on the documentation website. Initial plan Update docs: pin latest deps, fix version, expand API coverage, add .gitignore entries Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> Reset branch to main and re-apply docs-only changes Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> Fix docs for current codebase: correct version, class names, macros, and .gitignore Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> Add module docstring to docs/source/conf.py for ruff D100 compliance Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> Apply ruff fixes Ignore `mypy` errors

Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

…ing entry points) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

…docs (configuration, handle, concurrency) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Copilot AI assigned Copilot and greenc-FNAL Feb 13, 2026

Copilot started work on behalf of greenc-FNAL February 13, 2026 17:09 View session

Copilot AI changed the title ~~[WIP] Update branch with latest main and enhance features~~ Update Sphinx/Doxygen/Breathe docs: pin latest deps, fix config, expand API coverage Feb 13, 2026

Copilot AI requested a review from greenc-FNAL February 13, 2026 17:19

Copilot finished work on behalf of greenc-FNAL February 13, 2026 17:19

Copilot started work on behalf of greenc-FNAL February 13, 2026 18:03 View session

Copilot finished work on behalf of greenc-FNAL February 13, 2026 18:11

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 0712ae9 to 2095c80 Compare February 13, 2026 18:25

greenc-FNAL changed the base branch from jules-feature-sphinx-doxygen-breathe-setup to main February 13, 2026 18:30

greenc-FNAL marked this pull request as ready for review February 13, 2026 18:31

Copilot AI review requested due to automatic review settings February 13, 2026 18:31

Copilot started reviewing on behalf of greenc-FNAL February 13, 2026 18:31 View session

Copilot AI reviewed Feb 13, 2026

View reviewed changes

docs/source/conf.py Outdated Show resolved Hide resolved

Copilot started work on behalf of greenc-FNAL February 13, 2026 20:58 View session

Copilot finished work on behalf of greenc-FNAL February 13, 2026 21:00

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 824f679 to a7a5bf2 Compare February 14, 2026 00:18

greenc-FNAL marked this pull request as draft February 14, 2026 01:19

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch 2 times, most recently from dcbc52d to e416cbc Compare February 20, 2026 17:44

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from e416cbc to 85a095f Compare February 24, 2026 16:32

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 85a095f to a62c7df Compare March 4, 2026 18:52

Copilot started work on behalf of greenc-FNAL March 4, 2026 18:56 View session

Copilot finished work on behalf of greenc-FNAL March 4, 2026 19:00

Copilot started work on behalf of greenc-FNAL March 4, 2026 19:03 View session

Copilot AI changed the title ~~Update Sphinx/Doxygen/Breathe docs: pin latest deps, fix config, expand API coverage~~ Add Sphinx/Doxygen/Breathe documentation framework for phlex::experimental API Mar 4, 2026

Copilot finished work on behalf of greenc-FNAL March 4, 2026 19:07

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 31b7611 to 3b11ebf Compare March 4, 2026 19:59

greenc-FNAL marked this pull request as ready for review March 4, 2026 20:58

greenc-FNAL requested a review from Copilot March 4, 2026 21:05

Copilot started reviewing on behalf of greenc-FNAL March 4, 2026 21:06 View session

Copilot AI reviewed Mar 4, 2026

View reviewed changes

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 3b11ebf to a04ec85 Compare March 9, 2026 16:43

Copilot started work on behalf of greenc-FNAL March 9, 2026 17:29 View session

Copilot AI changed the title ~~Add Sphinx/Doxygen/Breathe documentation framework for phlex::experimental API~~ Add Sphinx/Doxygen/Breathe documentation framework for phlex and phlex::experimental API Mar 9, 2026

Copilot finished work on behalf of greenc-FNAL March 9, 2026 17:34

greenc-FNAL requested a review from Copilot March 9, 2026 18:30

Copilot started reviewing on behalf of greenc-FNAL March 9, 2026 18:31 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch 2 times, most recently from 4dc2b20 to 267fc43 Compare March 16, 2026 16:04

google-labs-jules bot and others added 4 commits March 16, 2026 14:17

Remove layer_sentry reference (class no longer exists in codebase)

e054de0

Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Add module_graph_proxy and source_graph_proxy API pages (new user-fac…

acffdae

…ing entry points) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Fix Doxyfile paths for repo-root invocation; add phlex-namespace API …

8934e85

…docs (configuration, handle, concurrency) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 267fc43 to 8934e85 Compare March 16, 2026 19:17

-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

		PREDEFINED = "BOOST_DLL_ALIAS(a,b)=" \
		"PHLEX_DETAIL_REGISTER_PLUGIN(...)="

		templates_path = ["_templates"]
		exclude_patterns = []

Conversation

Copilot AI commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation framework

Dependency pinning

API pages — phlex namespace

API pages — phlex::experimental namespace

Doxyfile configuration

Housekeeping

Uh oh!

greenc-FNAL commented Feb 13, 2026

Uh oh!

Copilot AI commented Feb 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

greenc-FNAL commented Feb 13, 2026

Uh oh!

github-actions bot commented Feb 13, 2026

Uh oh!

codecov bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

greenc-FNAL commented Mar 4, 2026

Uh oh!

Copilot AI commented Mar 4, 2026

Uh oh!

greenc-FNAL commented Mar 4, 2026

Uh oh!

Copilot AI commented Mar 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

greenc-FNAL commented Mar 9, 2026

Uh oh!

Copilot AI commented Mar 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

greenc-FNAL commented Mar 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Copilot AI commented Feb 13, 2026 •

edited

Loading

API pages — `phlex` namespace

API pages — `phlex::experimental` namespace

codecov bot commented Feb 13, 2026 •

edited

Loading