From afbc2a733bf5cadedb983e15868a93934725354d Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 16 Nov 2025 16:56:57 +0000 Subject: [PATCH 1/4] feature: Add initial Sphinx, Doxygen, and Breathe documentation framework 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 --- .gitignore | 4 ++++ docs/Doxyfile | 28 +++++++++++++++++++++++++ docs/requirements.txt | 3 +++ docs/source/api/declared_fold.rst | 6 ++++++ docs/source/api/declared_transform.rst | 6 ++++++ docs/source/api/declared_unfold.rst | 6 ++++++ docs/source/api/framework_graph.rst | 10 +++++++++ docs/source/api/graph_proxy.rst | 6 ++++++ docs/source/api/product_store.rst | 6 ++++++ docs/source/api/products.rst | 6 ++++++ docs/source/api/registrar.rst | 6 ++++++ docs/source/conf.py | 29 ++++++++++++++++++++++++++ docs/source/index.rst | 20 ++++++++++++++++++ 13 files changed, 136 insertions(+) create mode 100644 docs/Doxyfile create mode 100644 docs/requirements.txt create mode 100644 docs/source/api/declared_fold.rst create mode 100644 docs/source/api/declared_transform.rst create mode 100644 docs/source/api/declared_unfold.rst create mode 100644 docs/source/api/framework_graph.rst create mode 100644 docs/source/api/graph_proxy.rst create mode 100644 docs/source/api/product_store.rst create mode 100644 docs/source/api/products.rst create mode 100644 docs/source/api/registrar.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/.gitignore b/.gitignore index 931fc4922..f412f96b7 100644 --- a/.gitignore +++ b/.gitignore @@ -46,6 +46,10 @@ __pycache__/ *.pyc *.pyo +# Documentation build output +docs/doxygen/ +docs/build/ + # macOS .DS_Store # act (local workflow testing) diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 000000000..0777b9f1f --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,28 @@ +# Doxyfile + +# -- Project settings -------------------------------------------------------- +PROJECT_NAME = "Phlex" +PROJECT_BRIEF = "A framework for parallel, hierarchical, and layered execution of data-processing algorithms" +QUIET = YES + +# -- Input and output directories -------------------------------------------- +INPUT = ../phlex ../form +OUTPUT_DIRECTORY = doxygen +RECURSIVE = YES + +# -- Output formats ---------------------------------------------------------- +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES +XML_OUTPUT = xml + +# -- Source code parsing ----------------------------------------------------- +EXTRACT_ALL = YES +WARN_IF_UNDOCUMENTED = NO +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +FILE_PATTERNS = *.hpp *.cpp +EXCLUDE_PATTERNS = */detail/* +# Help Doxygen with some of the more complex macros +PREDEFINED = "BOOST_DLL_ALIAS(a,b)=" \ + "PHLEX_DETAIL_REGISTER_PLUGIN(...)=" diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..feec2aecc --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx>=9.1,<10 +breathe>=4.36,<5 +sphinx-rtd-theme>=3.1,<4 diff --git a/docs/source/api/declared_fold.rst b/docs/source/api/declared_fold.rst new file mode 100644 index 000000000..a2288aa21 --- /dev/null +++ b/docs/source/api/declared_fold.rst @@ -0,0 +1,6 @@ +declared_fold +============== + +.. doxygenclass:: phlex::experimental::declared_fold + :members: + :undoc-members: diff --git a/docs/source/api/declared_transform.rst b/docs/source/api/declared_transform.rst new file mode 100644 index 000000000..1a1a12e0c --- /dev/null +++ b/docs/source/api/declared_transform.rst @@ -0,0 +1,6 @@ +declared_transform +=================== + +.. doxygenclass:: phlex::experimental::declared_transform + :members: + :undoc-members: diff --git a/docs/source/api/declared_unfold.rst b/docs/source/api/declared_unfold.rst new file mode 100644 index 000000000..71a9f4b17 --- /dev/null +++ b/docs/source/api/declared_unfold.rst @@ -0,0 +1,6 @@ +declared_unfold +================ + +.. doxygenclass:: phlex::experimental::declared_unfold + :members: + :undoc-members: diff --git a/docs/source/api/framework_graph.rst b/docs/source/api/framework_graph.rst new file mode 100644 index 000000000..01c7641ee --- /dev/null +++ b/docs/source/api/framework_graph.rst @@ -0,0 +1,10 @@ +framework_graph +================ + +.. doxygenclass:: phlex::experimental::framework_graph + :members: + :undoc-members: + +.. doxygenclass:: phlex::experimental::layer_sentry + :members: + :undoc-members: diff --git a/docs/source/api/graph_proxy.rst b/docs/source/api/graph_proxy.rst new file mode 100644 index 000000000..b16176a65 --- /dev/null +++ b/docs/source/api/graph_proxy.rst @@ -0,0 +1,6 @@ +graph_proxy +============= + +.. doxygenclass:: phlex::experimental::graph_proxy + :members: + :undoc-members: diff --git a/docs/source/api/product_store.rst b/docs/source/api/product_store.rst new file mode 100644 index 000000000..785c5def8 --- /dev/null +++ b/docs/source/api/product_store.rst @@ -0,0 +1,6 @@ +product_store +============== + +.. doxygenclass:: phlex::experimental::product_store + :members: + :undoc-members: diff --git a/docs/source/api/products.rst b/docs/source/api/products.rst new file mode 100644 index 000000000..6449ce808 --- /dev/null +++ b/docs/source/api/products.rst @@ -0,0 +1,6 @@ +products +========= + +.. doxygenclass:: phlex::experimental::products + :members: + :undoc-members: diff --git a/docs/source/api/registrar.rst b/docs/source/api/registrar.rst new file mode 100644 index 000000000..0f545eeae --- /dev/null +++ b/docs/source/api/registrar.rst @@ -0,0 +1,6 @@ +registrar +========== + +.. doxygenclass:: phlex::experimental::registrar + :members: + :undoc-members: diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 000000000..d0855871d --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,29 @@ +# mypy: ignore-errors +"""Sphinx configuration for Phlex documentation.""" + +# -- Project information ----------------------------------------------------- + +project = "Phlex" +copyright = "2025-2026, The Phlex Developers" +author = "The Phlex Developers" +release = "0.1.0" + +# -- General configuration --------------------------------------------------- + +extensions = [ + "breathe", +] + +templates_path = ["_templates"] +exclude_patterns = [] + +# -- Options for HTML output ------------------------------------------------- + +html_theme = "sphinx_rtd_theme" + +# -- Breathe configuration ------------------------------------------------- + +breathe_projects = { + "Phlex": "../doxygen/xml/", +} +breathe_default_project = "Phlex" diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 000000000..150d01e0b --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. Phlex documentation master file, created by + sphinx-quickstart on Tue Nov 15 14:29:55 2025. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Phlex's documentation! +================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + api/graph_proxy + api/framework_graph + api/registrar + api/declared_transform + api/declared_fold + api/declared_unfold + api/product_store + api/products From 23f126acb255b63c38694bfad2cc2b372ae0d9c1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Mar 2026 18:59:43 +0000 Subject: [PATCH 2/4] Remove layer_sentry reference (class no longer exists in codebase) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> --- docs/source/api/framework_graph.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/source/api/framework_graph.rst b/docs/source/api/framework_graph.rst index 01c7641ee..3aaec3b96 100644 --- a/docs/source/api/framework_graph.rst +++ b/docs/source/api/framework_graph.rst @@ -4,7 +4,3 @@ framework_graph .. doxygenclass:: phlex::experimental::framework_graph :members: :undoc-members: - -.. doxygenclass:: phlex::experimental::layer_sentry - :members: - :undoc-members: From ea927fbc9c55bae68c8ccdec21f0c7fd07d4e9d4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Mar 2026 19:06:24 +0000 Subject: [PATCH 3/4] Add module_graph_proxy and source_graph_proxy API pages (new user-facing entry points) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> --- docs/source/api/module_graph_proxy.rst | 6 ++++++ docs/source/api/source_graph_proxy.rst | 6 ++++++ docs/source/index.rst | 2 ++ 3 files changed, 14 insertions(+) create mode 100644 docs/source/api/module_graph_proxy.rst create mode 100644 docs/source/api/source_graph_proxy.rst diff --git a/docs/source/api/module_graph_proxy.rst b/docs/source/api/module_graph_proxy.rst new file mode 100644 index 000000000..b59571813 --- /dev/null +++ b/docs/source/api/module_graph_proxy.rst @@ -0,0 +1,6 @@ +module_graph_proxy +=================== + +.. doxygenclass:: phlex::experimental::module_graph_proxy + :members: + :undoc-members: diff --git a/docs/source/api/source_graph_proxy.rst b/docs/source/api/source_graph_proxy.rst new file mode 100644 index 000000000..879598c35 --- /dev/null +++ b/docs/source/api/source_graph_proxy.rst @@ -0,0 +1,6 @@ +source_graph_proxy +=================== + +.. doxygenclass:: phlex::experimental::source_graph_proxy + :members: + :undoc-members: diff --git a/docs/source/index.rst b/docs/source/index.rst index 150d01e0b..fda8355ba 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,6 +10,8 @@ Welcome to Phlex's documentation! :maxdepth: 2 :caption: Contents: + api/module_graph_proxy + api/source_graph_proxy api/graph_proxy api/framework_graph api/registrar From 4dc2b206824f5fc58a4b55916aca0f1fe19a6342 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Mar 2026 17:33:07 +0000 Subject: [PATCH 4/4] Fix Doxyfile paths for repo-root invocation; add phlex-namespace API docs (configuration, handle, concurrency) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> --- docs/Doxyfile | 5 +++-- docs/source/api/concurrency.rst | 6 ++++++ docs/source/api/configuration.rst | 6 ++++++ docs/source/api/handle.rst | 6 ++++++ docs/source/index.rst | 15 ++++++++++++++- 5 files changed, 35 insertions(+), 3 deletions(-) create mode 100644 docs/source/api/concurrency.rst create mode 100644 docs/source/api/configuration.rst create mode 100644 docs/source/api/handle.rst diff --git a/docs/Doxyfile b/docs/Doxyfile index 0777b9f1f..625291833 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -6,8 +6,9 @@ PROJECT_BRIEF = "A framework for parallel, hierarchical, and layered executi QUIET = YES # -- Input and output directories -------------------------------------------- -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 RECURSIVE = YES # -- Output formats ---------------------------------------------------------- diff --git a/docs/source/api/concurrency.rst b/docs/source/api/concurrency.rst new file mode 100644 index 000000000..25d8af06c --- /dev/null +++ b/docs/source/api/concurrency.rst @@ -0,0 +1,6 @@ +concurrency +============ + +.. doxygenstruct:: phlex::concurrency + :members: + :undoc-members: diff --git a/docs/source/api/configuration.rst b/docs/source/api/configuration.rst new file mode 100644 index 000000000..b6872e6b5 --- /dev/null +++ b/docs/source/api/configuration.rst @@ -0,0 +1,6 @@ +configuration +============== + +.. doxygenclass:: phlex::configuration + :members: + :undoc-members: diff --git a/docs/source/api/handle.rst b/docs/source/api/handle.rst new file mode 100644 index 000000000..910f67a5a --- /dev/null +++ b/docs/source/api/handle.rst @@ -0,0 +1,6 @@ +handle +======= + +.. doxygenclass:: phlex::handle + :members: + :undoc-members: diff --git a/docs/source/index.rst b/docs/source/index.rst index fda8355ba..127360cff 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,15 +8,28 @@ Welcome to Phlex's documentation! .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Plugin entry points: api/module_graph_proxy api/source_graph_proxy api/graph_proxy api/framework_graph api/registrar + +.. toctree:: + :maxdepth: 2 + :caption: Algorithm nodes: + api/declared_transform api/declared_fold api/declared_unfold + +.. toctree:: + :maxdepth: 2 + :caption: Data model: + + api/configuration + api/handle + api/concurrency api/product_store api/products