From 45cb921a4b8e7c2584648113245ec72bc59acd33 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Mon, 22 Dec 2025 17:33:21 -0700 Subject: [PATCH 01/40] Move .rst files to docs/sphinx --- docs/{ => sphinx}/async.rst | 0 docs/{ => sphinx}/batch.rst | 0 docs/{ => sphinx}/config_build.rst | 0 docs/{ => sphinx}/core.rst | 0 docs/{ => sphinx}/driver.rst | 0 docs/{ => sphinx}/errors.rst | 0 docs/{ => sphinx}/file.rst | 0 docs/{ => sphinx}/introduction.rst | 0 docs/{ => sphinx}/misc_api.rst | 0 docs/{ => sphinx}/nvidia_compat.rst | 0 docs/{ => sphinx}/rdma.rst | 0 11 files changed, 0 insertions(+), 0 deletions(-) rename docs/{ => sphinx}/async.rst (100%) rename docs/{ => sphinx}/batch.rst (100%) rename docs/{ => sphinx}/config_build.rst (100%) rename docs/{ => sphinx}/core.rst (100%) rename docs/{ => sphinx}/driver.rst (100%) rename docs/{ => sphinx}/errors.rst (100%) rename docs/{ => sphinx}/file.rst (100%) rename docs/{ => sphinx}/introduction.rst (100%) rename docs/{ => sphinx}/misc_api.rst (100%) rename docs/{ => sphinx}/nvidia_compat.rst (100%) rename docs/{ => sphinx}/rdma.rst (100%) diff --git a/docs/async.rst b/docs/sphinx/async.rst similarity index 100% rename from docs/async.rst rename to docs/sphinx/async.rst diff --git a/docs/batch.rst b/docs/sphinx/batch.rst similarity index 100% rename from docs/batch.rst rename to docs/sphinx/batch.rst diff --git a/docs/config_build.rst b/docs/sphinx/config_build.rst similarity index 100% rename from docs/config_build.rst rename to docs/sphinx/config_build.rst diff --git a/docs/core.rst b/docs/sphinx/core.rst similarity index 100% rename from docs/core.rst rename to docs/sphinx/core.rst diff --git a/docs/driver.rst b/docs/sphinx/driver.rst similarity index 100% rename from docs/driver.rst rename to docs/sphinx/driver.rst diff --git a/docs/errors.rst b/docs/sphinx/errors.rst similarity index 100% rename from docs/errors.rst rename to docs/sphinx/errors.rst diff --git a/docs/file.rst b/docs/sphinx/file.rst similarity index 100% rename from docs/file.rst rename to docs/sphinx/file.rst diff --git a/docs/introduction.rst b/docs/sphinx/introduction.rst similarity index 100% rename from docs/introduction.rst rename to docs/sphinx/introduction.rst diff --git a/docs/misc_api.rst b/docs/sphinx/misc_api.rst similarity index 100% rename from docs/misc_api.rst rename to docs/sphinx/misc_api.rst diff --git a/docs/nvidia_compat.rst b/docs/sphinx/nvidia_compat.rst similarity index 100% rename from docs/nvidia_compat.rst rename to docs/sphinx/nvidia_compat.rst diff --git a/docs/rdma.rst b/docs/sphinx/rdma.rst similarity index 100% rename from docs/rdma.rst rename to docs/sphinx/rdma.rst From 54f0077c49e2d6add4b6f9a22df875a50bca8ad8 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 17 Mar 2026 11:42:54 -0600 Subject: [PATCH 02/40] Add .readthedocs.yaml --- .readthedocs.yaml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..3afbabbc --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,18 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +sphinx: + configuration: docs/conf.py + +formats: [] + +python: + install: + - requirements: docs/sphinx/requirements.txt + +build: + os: ubuntu-22.04 + tools: + python: "3.10" From 64425b900887a47b27bb45252ac214f7095bf90f Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 17 Mar 2026 14:09:09 -0600 Subject: [PATCH 03/40] Move Doxyfile.in to docs/doxygen/ --- cmake/AISDocumentation.cmake | 2 +- docs/{ => doxygen}/Doxyfile.in | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/{ => doxygen}/Doxyfile.in (100%) diff --git a/cmake/AISDocumentation.cmake b/cmake/AISDocumentation.cmake index 2407978f..ecf39a68 100644 --- a/cmake/AISDocumentation.cmake +++ b/cmake/AISDocumentation.cmake @@ -24,7 +24,7 @@ if(AIS_BUILD_DOCS) set(AIS_DOXYFILE ${AIS_DOC_PATH}/Doxyfile) # Create the Doxyfile from the input file - configure_file("docs/Doxyfile.in" ${AIS_DOXYFILE}) + configure_file("docs/doxygen/Doxyfile.in" ${AIS_DOXYFILE}) # Set the output directory set(DOXYGEN_OUT ${AIS_DOC_PATH}) diff --git a/docs/Doxyfile.in b/docs/doxygen/Doxyfile.in similarity index 100% rename from docs/Doxyfile.in rename to docs/doxygen/Doxyfile.in From 2e7d1e27a3f60f579a8733b5df4fb5bc1ebf5a1f Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 17 Mar 2026 14:17:46 -0600 Subject: [PATCH 04/40] Move API Sphinx docs to docs/api --- docs/{sphinx => api}/async.rst | 0 docs/{sphinx => api}/batch.rst | 0 docs/{sphinx => api}/core.rst | 0 docs/{sphinx => api}/driver.rst | 0 docs/{sphinx => api}/errors.rst | 0 docs/{sphinx => api}/file.rst | 0 docs/{sphinx => api}/misc_api.rst | 0 docs/{sphinx => api}/rdma.rst | 0 8 files changed, 0 insertions(+), 0 deletions(-) rename docs/{sphinx => api}/async.rst (100%) rename docs/{sphinx => api}/batch.rst (100%) rename docs/{sphinx => api}/core.rst (100%) rename docs/{sphinx => api}/driver.rst (100%) rename docs/{sphinx => api}/errors.rst (100%) rename docs/{sphinx => api}/file.rst (100%) rename docs/{sphinx => api}/misc_api.rst (100%) rename docs/{sphinx => api}/rdma.rst (100%) diff --git a/docs/sphinx/async.rst b/docs/api/async.rst similarity index 100% rename from docs/sphinx/async.rst rename to docs/api/async.rst diff --git a/docs/sphinx/batch.rst b/docs/api/batch.rst similarity index 100% rename from docs/sphinx/batch.rst rename to docs/api/batch.rst diff --git a/docs/sphinx/core.rst b/docs/api/core.rst similarity index 100% rename from docs/sphinx/core.rst rename to docs/api/core.rst diff --git a/docs/sphinx/driver.rst b/docs/api/driver.rst similarity index 100% rename from docs/sphinx/driver.rst rename to docs/api/driver.rst diff --git a/docs/sphinx/errors.rst b/docs/api/errors.rst similarity index 100% rename from docs/sphinx/errors.rst rename to docs/api/errors.rst diff --git a/docs/sphinx/file.rst b/docs/api/file.rst similarity index 100% rename from docs/sphinx/file.rst rename to docs/api/file.rst diff --git a/docs/sphinx/misc_api.rst b/docs/api/misc_api.rst similarity index 100% rename from docs/sphinx/misc_api.rst rename to docs/api/misc_api.rst diff --git a/docs/sphinx/rdma.rst b/docs/api/rdma.rst similarity index 100% rename from docs/sphinx/rdma.rst rename to docs/api/rdma.rst From 13289700576e9cb258614f26b53daacd294b90f1 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 17 Mar 2026 14:23:25 -0600 Subject: [PATCH 05/40] Move misc Sphinx docs to docs/ --- docs/{sphinx => }/config_build.rst | 0 docs/{sphinx => }/introduction.rst | 0 docs/{sphinx => }/nvidia_compat.rst | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename docs/{sphinx => }/config_build.rst (100%) rename docs/{sphinx => }/introduction.rst (100%) rename docs/{sphinx => }/nvidia_compat.rst (100%) diff --git a/docs/sphinx/config_build.rst b/docs/config_build.rst similarity index 100% rename from docs/sphinx/config_build.rst rename to docs/config_build.rst diff --git a/docs/sphinx/introduction.rst b/docs/introduction.rst similarity index 100% rename from docs/sphinx/introduction.rst rename to docs/introduction.rst diff --git a/docs/sphinx/nvidia_compat.rst b/docs/nvidia_compat.rst similarity index 100% rename from docs/sphinx/nvidia_compat.rst rename to docs/nvidia_compat.rst From ebd8d3aafe7d56c35682c4f14a8dd46fb772efa0 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 17 Mar 2026 14:38:00 -0600 Subject: [PATCH 06/40] Add toc and requirements Also adds a blank hipify.rst file --- docs/hipify.rst | 2 + docs/sphinx/_toc.yml | 43 ++++++ docs/sphinx/requirements.in | 1 + docs/sphinx/requirements.txt | 278 +++++++++++++++++++++++++++++++++++ 4 files changed, 324 insertions(+) create mode 100644 docs/hipify.rst create mode 100644 docs/sphinx/_toc.yml create mode 100644 docs/sphinx/requirements.in create mode 100644 docs/sphinx/requirements.txt diff --git a/docs/hipify.rst b/docs/hipify.rst new file mode 100644 index 00000000..f47bdfee --- /dev/null +++ b/docs/hipify.rst @@ -0,0 +1,2 @@ +hipify +====== diff --git a/docs/sphinx/_toc.yml b/docs/sphinx/_toc.yml new file mode 100644 index 00000000..c6fcd4eb --- /dev/null +++ b/docs/sphinx/_toc.yml @@ -0,0 +1,43 @@ +defaults: + numbered: False +root: index +subtrees: + +- entries: + - file: introduction.rst + title: Introduction + +- caption: Build and install + entries: + - file: config_build.rst + title: Configure and build + - file: sanitizers.rst + title: Sanitizers + +- caption: Using hipFile + entries: + - file: hipify.rst + title: hipify + - file: nvidia_compat.rst + title: cuFile compatibility + - file: fio.rst + title: fio support + +- caption: API reference + entries: + - file: api/errors.rst + title: Errors + - file: api/core.rst + title: Core + - file: api/driver.rst + title: Drivers + - file: api/file.rst + title: File operations + - file: api/async.rst + title: Asynchronous operatoins + - file: api/batch.rst + title: Batch operations + - file: api/rdma.rst + title: RDMA + - file: api/misc_api.rst + title: Other diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in new file mode 100644 index 00000000..aff7ac0b --- /dev/null +++ b/docs/sphinx/requirements.in @@ -0,0 +1 @@ +rocm-docs-core==1.31.2 diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt new file mode 100644 index 00000000..c32119cd --- /dev/null +++ b/docs/sphinx/requirements.txt @@ -0,0 +1,278 @@ +# +# This file is autogenerated by pip-compile with Python 3.10 +# by the following command: +# +# pip-compile requirements.in +# +accessible-pygments==0.0.5 + # via pydata-sphinx-theme +alabaster==1.0.0 + # via sphinx +asttokens==3.0.0 + # via stack-data +attrs==25.3.0 + # via + # jsonschema + # jupyter-cache + # referencing +babel==2.17.0 + # via + # pydata-sphinx-theme + # sphinx +beautifulsoup4==4.13.4 + # via pydata-sphinx-theme +breathe==4.36.0 + # via rocm-docs-core +certifi==2025.4.26 + # via requests +cffi==2.0.0 + # via + # cryptography + # pynacl +charset-normalizer==3.4.2 + # via requests +click==8.1.8 + # via + # jupyter-cache + # sphinx-external-toc +comm==0.2.2 + # via ipykernel +cryptography==44.0.3 + # via pyjwt +debugpy==1.8.14 + # via ipykernel +decorator==5.2.1 + # via ipython +deprecated==1.2.18 + # via pygithub +docutils==0.21.2 + # via + # myst-parser + # pydata-sphinx-theme + # sphinx +exceptiongroup==1.2.2 + # via ipython +executing==2.2.0 + # via stack-data +fastjsonschema==2.21.1 + # via + # nbformat + # rocm-docs-core +gitdb==4.0.12 + # via gitpython +gitpython==3.1.44 + # via rocm-docs-core +greenlet==3.2.1 + # via sqlalchemy +idna==3.10 + # via requests +imagesize==1.4.1 + # via sphinx +importlib-metadata==8.7.0 + # via + # jupyter-cache + # myst-nb +ipykernel==6.29.5 + # via myst-nb +ipython==8.36.0 + # via + # ipykernel + # myst-nb +jedi==0.19.2 + # via ipython +jinja2==3.1.6 + # via + # myst-parser + # sphinx +jsonschema==4.23.0 + # via nbformat +jsonschema-specifications==2025.4.1 + # via jsonschema +jupyter-cache==1.0.1 + # via myst-nb +jupyter-client==8.6.3 + # via + # ipykernel + # nbclient +jupyter-core==5.7.2 + # via + # ipykernel + # jupyter-client + # nbclient + # nbformat +markdown-it-py==3.0.0 + # via + # mdit-py-plugins + # myst-parser +markupsafe==3.0.2 + # via jinja2 +matplotlib-inline==0.1.7 + # via + # ipykernel + # ipython +mdit-py-plugins==0.4.2 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py +myst-nb==1.2.0 + # via rocm-docs-core +myst-parser==4.0.1 + # via myst-nb +nbclient==0.10.2 + # via + # jupyter-cache + # myst-nb +nbformat==5.10.4 + # via + # jupyter-cache + # myst-nb + # nbclient +nest-asyncio==1.6.0 + # via ipykernel +packaging==25.0 + # via + # ipykernel + # pydata-sphinx-theme + # sphinx +parso==0.8.4 + # via jedi +pexpect==4.9.0 + # via ipython +platformdirs==4.3.8 + # via jupyter-core +prompt-toolkit==3.0.51 + # via ipython +psutil==7.0.0 + # via ipykernel +ptyprocess==0.7.0 + # via pexpect +pure-eval==0.2.3 + # via stack-data +pycparser==2.22 + # via cffi +pydata-sphinx-theme==0.15.4 + # via + # rocm-docs-core + # sphinx-book-theme +pygithub==2.6.1 + # via rocm-docs-core +pygments==2.19.1 + # via + # accessible-pygments + # ipython + # pydata-sphinx-theme + # sphinx +pyjwt[crypto]==2.10.1 + # via pygithub +pynacl==1.6.2 + # via pygithub +python-dateutil==2.9.0.post0 + # via jupyter-client +pyyaml==6.0.2 + # via + # jupyter-cache + # myst-nb + # myst-parser + # rocm-docs-core + # sphinx-external-toc +pyzmq==26.4.0 + # via + # ipykernel + # jupyter-client +referencing==0.36.2 + # via + # jsonschema + # jsonschema-specifications +requests==2.32.4 + # via + # pygithub + # sphinx +rocm-docs-core==1.31.2 + # via -r requirements.in +rpds-py==0.24.0 + # via + # jsonschema + # referencing +six==1.17.0 + # via python-dateutil +smmap==5.0.2 + # via gitdb +snowballstemmer==3.0.0.1 + # via sphinx +soupsieve==2.7 + # via beautifulsoup4 +sphinx==8.1.3 + # via + # breathe + # myst-nb + # myst-parser + # pydata-sphinx-theme + # rocm-docs-core + # sphinx-book-theme + # sphinx-copybutton + # sphinx-design + # sphinx-external-toc + # sphinx-notfound-page +sphinx-book-theme==1.1.4 + # via rocm-docs-core +sphinx-copybutton==0.5.2 + # via rocm-docs-core +sphinx-design==0.6.1 + # via rocm-docs-core +sphinx-external-toc==1.0.1 + # via rocm-docs-core +sphinx-notfound-page==1.1.0 + # via rocm-docs-core +sphinxcontrib-applehelp==2.0.0 + # via sphinx +sphinxcontrib-devhelp==2.0.0 + # via sphinx +sphinxcontrib-htmlhelp==2.1.0 + # via sphinx +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==2.0.0 + # via sphinx +sphinxcontrib-serializinghtml==2.0.0 + # via sphinx +sqlalchemy==2.0.40 + # via jupyter-cache +stack-data==0.6.3 + # via ipython +tabulate==0.9.0 + # via jupyter-cache +tomli==2.2.1 + # via sphinx +tornado==6.5.1 + # via + # ipykernel + # jupyter-client +traitlets==5.14.3 + # via + # comm + # ipykernel + # ipython + # jupyter-client + # jupyter-core + # matplotlib-inline + # nbclient + # nbformat +typing-extensions==4.13.2 + # via + # beautifulsoup4 + # ipython + # myst-nb + # pydata-sphinx-theme + # pygithub + # referencing + # sqlalchemy +urllib3==2.6.3 + # via + # pygithub + # requests +wcwidth==0.2.13 + # via prompt-toolkit +wrapt==1.17.2 + # via deprecated +zipp==3.21.0 + # via importlib-metadata From cfeebcb9ff3900b0b0872d527699e98dee36e97b Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 17 Mar 2026 14:46:47 -0600 Subject: [PATCH 07/40] Add conf.py --- docs/conf.py | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/conf.py diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..5feb5a5d --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,23 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +from rocm_docs import ROCmDocs + +version_number = "0.2.0" +left_nav_title = f"hipFile {version_number} documentation" + +# for PDF output on Read the Docs +project = "hipFile" +author = "Advanced Micro Devices, Inc." +copyright = "Copyright (c) Advanced Micro Devices, Inc. All rights reserved." +version = version_number +release = version_number + +external_toc_path = "./sphinx/_toc.yml" + +docs_core = ROCmDocs(left_nav_title) +docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml") +docs_core.setup() From f275f90423527da12a84c88aab428a7345c36f5c Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 17 Mar 2026 15:32:40 -0600 Subject: [PATCH 08/40] Fixes that make Sphinx "work" --- docs/conf.py | 6 +++- docs/index.rst | 42 +++++++++++++++++++++++++++ docs/sphinx/{_toc.yml => _toc.yml.in} | 2 +- 3 files changed, 48 insertions(+), 2 deletions(-) create mode 100644 docs/index.rst rename docs/sphinx/{_toc.yml => _toc.yml.in} (95%) diff --git a/docs/conf.py b/docs/conf.py index 5feb5a5d..de844a56 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,7 +10,7 @@ left_nav_title = f"hipFile {version_number} documentation" # for PDF output on Read the Docs -project = "hipFile" +project = "rocSHMEM" author = "Advanced Micro Devices, Inc." copyright = "Copyright (c) Advanced Micro Devices, Inc. All rights reserved." version = version_number @@ -21,3 +21,7 @@ docs_core = ROCmDocs(left_nav_title) docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml") docs_core.setup() + +external_projects_current_project = "rocshmem" +for sphinx_var in ROCmDocs.SPHINX_VARS: + globals()[sphinx_var] = getattr(docs_core, sphinx_var) diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..e1303d1b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,42 @@ +.. meta:: + :description: hipFile does hipFile stuff + :keywords: hipFile, ROCm, storage, library, API, DMA + +**************************** +rocSHMEM documentation +**************************** + +hipFile introduction goes here. For more information, see :doc:`introduction`. + +The hipFile public repository is located at ``_. + +.. grid:: 2 + :gutter: 3 + + .. grid-item-card:: Build and install + + * :doc:`Configure and build <./config_build>` + * :doc:`Sanitizers <./sanitizers>` + + .. grid-item-card:: Using hipFile + + * :doc:`hipify <./hipify>` + * :doc:`NVIDIA compatibility <./nvidia_compat>` + * :doc:`fio <./fio>` + + .. grid-item-card:: API reference + + * :doc:`Errors <./api/errors>` + * :doc:`Core API<./api/core>` + * :doc:`Drivers <./api/driver>` + * :doc:`File operations <./api/file>` + * :doc:`Asynchronous operations <./api/async>` + * :doc:`Batch operations <./api/batch>` + * :doc:`RDMA <./api/rdma>` + * :doc:`Other <./api/misc_api>` + +To contribute to the documentation, refer to +`Contributing to ROCm `_. + +You can find licensing information on the +`Licensing `_ page. diff --git a/docs/sphinx/_toc.yml b/docs/sphinx/_toc.yml.in similarity index 95% rename from docs/sphinx/_toc.yml rename to docs/sphinx/_toc.yml.in index c6fcd4eb..930411f6 100644 --- a/docs/sphinx/_toc.yml +++ b/docs/sphinx/_toc.yml.in @@ -34,7 +34,7 @@ subtrees: - file: api/file.rst title: File operations - file: api/async.rst - title: Asynchronous operatoins + title: Asynchronous operations - file: api/batch.rst title: Batch operations - file: api/rdma.rst From c344af6525b93ac9b6e78b96985efb08c8e96567 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Tue, 17 Mar 2026 15:37:18 -0600 Subject: [PATCH 09/40] Add stats_collection to Sphinx --- docs/index.rst | 1 + docs/sphinx/_toc.yml.in | 2 ++ 2 files changed, 3 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index e1303d1b..fbba6d4c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,6 +23,7 @@ The hipFile public repository is located at ``_ * :doc:`hipify <./hipify>` * :doc:`NVIDIA compatibility <./nvidia_compat>` * :doc:`fio <./fio>` + * :doc:`Collecting statistics <./stats_collection>` .. grid-item-card:: API reference diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 930411f6..c4d32d37 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -22,6 +22,8 @@ subtrees: title: cuFile compatibility - file: fio.rst title: fio support + - file: stats_collection.rst + title: Collecting statistics - caption: API reference entries: From 48bd17ac5d733d26a534e15e7327b18141d454ce Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 18 Mar 2026 11:05:31 -0600 Subject: [PATCH 10/40] Fix index.rst rocSHMEM comment --- docs/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index fbba6d4c..ef2f7cf3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,9 +2,9 @@ :description: hipFile does hipFile stuff :keywords: hipFile, ROCm, storage, library, API, DMA -**************************** -rocSHMEM documentation -**************************** +********************* +hipFile documentation +********************* hipFile introduction goes here. For more information, see :doc:`introduction`. From 2d48924129848b91566c458c33bb5e954b1529cd Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 18 Mar 2026 11:06:24 -0600 Subject: [PATCH 11/40] Fix missing space in index.rst --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index ef2f7cf3..73c3ef1f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,7 +28,7 @@ The hipFile public repository is located at ``_ .. grid-item-card:: API reference * :doc:`Errors <./api/errors>` - * :doc:`Core API<./api/core>` + * :doc:`Core API <./api/core>` * :doc:`Drivers <./api/driver>` * :doc:`File operations <./api/file>` * :doc:`Asynchronous operations <./api/async>` From b76d4944dbcfcb71e69b78fb686186a0e155bd64 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 18 Mar 2026 11:10:51 -0600 Subject: [PATCH 12/40] Add a comment block to _toc.yml.in --- docs/sphinx/_toc.yml.in | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index c4d32d37..1fcaff2e 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -1,3 +1,7 @@ +# This file is a template for the Sphinx table of contents. +# A build step is expected to generate `_toc.yml` from this `_toc.yml.in` +# file before running the Sphinx build (see docs/conf.py configuration). + defaults: numbered: False root: index From 1def73c516679656ce6d12e26b50ccee25537c71 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 18 Mar 2026 11:13:00 -0600 Subject: [PATCH 13/40] Fix correctness and formatting in .readthedocs.yaml --- .readthedocs.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 3afbabbc..f35d5c2f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -4,15 +4,15 @@ version: 2 sphinx: - configuration: docs/conf.py + configuration: docs/conf.py formats: [] python: - install: - - requirements: docs/sphinx/requirements.txt + install: + - requirements: docs/sphinx/requirements.txt build: - os: ubuntu-22.04 - tools: - python: "3.10" + os: ubuntu-22.04 + tools: + python: "3.10" From 8acfbad85b6048f9dd165383982ba43cbcff1505 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 18 Mar 2026 11:20:57 -0600 Subject: [PATCH 14/40] Suppress pylint complaints on conf.py --- docs/conf.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index de844a56..f83db6b4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,6 +4,11 @@ # list see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +# Pylint is NOT happy with the naming scheme ROCm chose +# pylint: disable=invalid-name + +"""This file is for configuring hipFile documentation""" + from rocm_docs import ROCmDocs version_number = "0.2.0" @@ -12,7 +17,9 @@ # for PDF output on Read the Docs project = "rocSHMEM" author = "Advanced Micro Devices, Inc." +# pylint: disable=redefined-builtin copyright = "Copyright (c) Advanced Micro Devices, Inc. All rights reserved." +# pylint: enable=redefined-builtin version = version_number release = version_number From 5b6c4edb5a907f5f9fd860c70a1b74082dc61e8b Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 18 Mar 2026 11:48:22 -0600 Subject: [PATCH 15/40] Add rocm_docs to pip list --- .github/workflows/pylint.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/pylint.yml b/.github/workflows/pylint.yml index 27311aed..5e3492bb 100644 --- a/.github/workflows/pylint.yml +++ b/.github/workflows/pylint.yml @@ -18,11 +18,12 @@ jobs: - name: Set up Python uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 #v6.2.0 - - name: Set up pylint and black + - name: Install packages run: | python -m pip install --upgrade pip python -m pip install pylint python -m pip install black + python -m pip install rocm_docs - name: Lint all Python files run: | From d4a3e1d12dc4c9284e368b3c27753485ddcb427a Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 18 Mar 2026 11:51:48 -0600 Subject: [PATCH 16/40] Fix rocm_docs package typo --- .github/workflows/pylint.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pylint.yml b/.github/workflows/pylint.yml index 5e3492bb..e0606ca1 100644 --- a/.github/workflows/pylint.yml +++ b/.github/workflows/pylint.yml @@ -23,7 +23,7 @@ jobs: python -m pip install --upgrade pip python -m pip install pylint python -m pip install black - python -m pip install rocm_docs + python -m pip install rocm-docs-core - name: Lint all Python files run: | From dc8c8026e42227ec35064a7061dde815611b591f Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 18 Mar 2026 14:51:32 -0600 Subject: [PATCH 17/40] First cut at moving sphinx generation to CMake --- cmake/AISDocumentation.cmake | 58 +++++- docs/doxygen/Doxyfile.in | 2 +- docs/sphinx/{_toc.yml.in => _toc.yml} | 4 - docs/{ => sphinx}/conf.py | 17 +- docs/sphinx/requirements.in | 1 - docs/sphinx/requirements.txt | 278 -------------------------- 6 files changed, 64 insertions(+), 296 deletions(-) rename docs/sphinx/{_toc.yml.in => _toc.yml} (81%) rename docs/{ => sphinx}/conf.py (68%) delete mode 100644 docs/sphinx/requirements.in delete mode 100644 docs/sphinx/requirements.txt diff --git a/cmake/AISDocumentation.cmake b/cmake/AISDocumentation.cmake index ecf39a68..68787f92 100644 --- a/cmake/AISDocumentation.cmake +++ b/cmake/AISDocumentation.cmake @@ -13,28 +13,66 @@ option(AIS_BUILD_DOCS "Build the hipFile docs (requires Doxygen, Sphinx, and Bre if(AIS_BUILD_DOCS) find_package(Doxygen REQUIRED) + find_package(Python3 REQUIRED COMPONENTS Interpreter) + + # Verify Sphinx + rocm_docs are available + execute_process( + COMMAND "${Python3_EXECUTABLE}" -c "import rocm_docs" + RESULT_VARIABLE _rocm_docs_found + OUTPUT_QUIET ERROR_QUIET + ) + if(NOT _rocm_docs_found EQUAL 0) + message(FATAL_ERROR "rocm_docs Python package not found. Install it with: pip install rocm-docs-core") + endif() # Set Doxygen input (pasted into Doxyfile.in) set(AIS_DOXYFILE_INPUT "${HIPFILE_ROOT_PATH}/include") - + # Set the path to the documentation set(AIS_DOC_PATH "${CMAKE_CURRENT_BINARY_DIR}/docs") - + # Set the Doxyfile install location - set(AIS_DOXYFILE ${AIS_DOC_PATH}/Doxyfile) + set(AIS_DOXYFILE "${AIS_DOC_PATH}/doxygen/Doxyfile") + + # Doxygen XML output dir (consumed by Breathe inside Sphinx) + set(AIS_DOXYGEN_XML_DIR "${AIS_DOC_PATH}/doxygen/xml") # Create the Doxyfile from the input file configure_file("docs/doxygen/Doxyfile.in" ${AIS_DOXYFILE}) - # Set the output directory - set(DOXYGEN_OUT ${AIS_DOC_PATH}) + # Sphinx HTML output dir + set(AIS_SPHINX_BUILD_DIR "${AIS_DOC_PATH}/html") - # Configure the documentation build - add_custom_target("doc" - COMMAND ${DOXYGEN_EXECUTABLE} ${AIS_DOXYFILE} - WORKING_DIRECTORY ${AIS_DOC_PATH} - COMMENT "Generating hipFile API documentation with Doxygen" + # Build docs: Doxygen first, then Sphinx (which pulls in rocm_docs via conf.py) + add_custom_target(doc + # Step 1: Run Doxygen to produce XML for Breathe + COMMAND "${DOXYGEN_EXECUTABLE}" "${AIS_DOXYFILE}" + # Step 2: Run Sphinx, injecting the Doxygen paths via environment + COMMAND + ${CMAKE_COMMAND} -E env + "DOXYFILE_PATH=${AIS_DOXYFILE}" + "DOXYGEN_ROOT=${AIS_DOC_PATH}/doxygen" + "DOXYGEN_XML_DIR=${AIS_DOXYGEN_XML_DIR}" + "${Python3_EXECUTABLE}" -m sphinx + -b html + -C + -c "${CMAKE_CURRENT_SOURCE_DIR}/docs/sphinx" + "${CMAKE_CURRENT_SOURCE_DIR}/docs" + "${AIS_SPHINX_BUILD_DIR}" + WORKING_DIRECTORY "${AIS_DOC_PATH}" + COMMENT "Generating hipFile API documentation with Doxygen + Sphinx (rocm_docs)" VERBATIM ) + # Set the output directory + #set(DOXYGEN_OUT ${AIS_DOC_PATH}) + + # Configure the documentation build + #add_custom_target("doc" + # COMMAND ${DOXYGEN_EXECUTABLE} ${AIS_DOXYFILE} + # WORKING_DIRECTORY ${AIS_DOC_PATH} + # COMMENT "Generating hipFile API documentation with Doxygen" + # VERBATIM + #) + endif() diff --git a/docs/doxygen/Doxyfile.in b/docs/doxygen/Doxyfile.in index 70058fb9..b9a60f43 100644 --- a/docs/doxygen/Doxyfile.in +++ b/docs/doxygen/Doxyfile.in @@ -68,7 +68,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = +OUTPUT_DIRECTORY = @AIS_DOC_PATH@/doxygen # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096 # sub-directories (in 2 levels) under the output directory of each output format diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml similarity index 81% rename from docs/sphinx/_toc.yml.in rename to docs/sphinx/_toc.yml index 1fcaff2e..c4d32d37 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml @@ -1,7 +1,3 @@ -# This file is a template for the Sphinx table of contents. -# A build step is expected to generate `_toc.yml` from this `_toc.yml.in` -# file before running the Sphinx build (see docs/conf.py configuration). - defaults: numbered: False root: index diff --git a/docs/conf.py b/docs/sphinx/conf.py similarity index 68% rename from docs/conf.py rename to docs/sphinx/conf.py index f83db6b4..59382e09 100644 --- a/docs/conf.py +++ b/docs/sphinx/conf.py @@ -9,6 +9,7 @@ """This file is for configuring hipFile documentation""" +import os from rocm_docs import ROCmDocs version_number = "0.2.0" @@ -22,13 +23,25 @@ # pylint: enable=redefined-builtin version = version_number release = version_number +external_projects_current_project = "rocshmem" external_toc_path = "./sphinx/_toc.yml" docs_core = ROCmDocs(left_nav_title) -docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml") + +doxygen_root = os.environ.get("DOXYGEN_ROOT") +doxygen_xml_dir = os.environ.get("DOXYGEN_XML_DIR") + +if not doxygen_root or not doxygen_xml_dir: + raise RuntimeError( + "DOXYGEN_ROOT and DOXYGEN_XML_DIR must be set. " + "Build this documentation via CMake, not directly with sphinx-build." + ) + +docs_core.run_doxygen(doxygen_root=doxygen_root, doxygen_path=doxygen_xml_dir) + docs_core.setup() -external_projects_current_project = "rocshmem" +# Transfer all Sphinx config variables into this module's global scope for sphinx_var in ROCmDocs.SPHINX_VARS: globals()[sphinx_var] = getattr(docs_core, sphinx_var) diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in deleted file mode 100644 index aff7ac0b..00000000 --- a/docs/sphinx/requirements.in +++ /dev/null @@ -1 +0,0 @@ -rocm-docs-core==1.31.2 diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt deleted file mode 100644 index c32119cd..00000000 --- a/docs/sphinx/requirements.txt +++ /dev/null @@ -1,278 +0,0 @@ -# -# This file is autogenerated by pip-compile with Python 3.10 -# by the following command: -# -# pip-compile requirements.in -# -accessible-pygments==0.0.5 - # via pydata-sphinx-theme -alabaster==1.0.0 - # via sphinx -asttokens==3.0.0 - # via stack-data -attrs==25.3.0 - # via - # jsonschema - # jupyter-cache - # referencing -babel==2.17.0 - # via - # pydata-sphinx-theme - # sphinx -beautifulsoup4==4.13.4 - # via pydata-sphinx-theme -breathe==4.36.0 - # via rocm-docs-core -certifi==2025.4.26 - # via requests -cffi==2.0.0 - # via - # cryptography - # pynacl -charset-normalizer==3.4.2 - # via requests -click==8.1.8 - # via - # jupyter-cache - # sphinx-external-toc -comm==0.2.2 - # via ipykernel -cryptography==44.0.3 - # via pyjwt -debugpy==1.8.14 - # via ipykernel -decorator==5.2.1 - # via ipython -deprecated==1.2.18 - # via pygithub -docutils==0.21.2 - # via - # myst-parser - # pydata-sphinx-theme - # sphinx -exceptiongroup==1.2.2 - # via ipython -executing==2.2.0 - # via stack-data -fastjsonschema==2.21.1 - # via - # nbformat - # rocm-docs-core -gitdb==4.0.12 - # via gitpython -gitpython==3.1.44 - # via rocm-docs-core -greenlet==3.2.1 - # via sqlalchemy -idna==3.10 - # via requests -imagesize==1.4.1 - # via sphinx -importlib-metadata==8.7.0 - # via - # jupyter-cache - # myst-nb -ipykernel==6.29.5 - # via myst-nb -ipython==8.36.0 - # via - # ipykernel - # myst-nb -jedi==0.19.2 - # via ipython -jinja2==3.1.6 - # via - # myst-parser - # sphinx -jsonschema==4.23.0 - # via nbformat -jsonschema-specifications==2025.4.1 - # via jsonschema -jupyter-cache==1.0.1 - # via myst-nb -jupyter-client==8.6.3 - # via - # ipykernel - # nbclient -jupyter-core==5.7.2 - # via - # ipykernel - # jupyter-client - # nbclient - # nbformat -markdown-it-py==3.0.0 - # via - # mdit-py-plugins - # myst-parser -markupsafe==3.0.2 - # via jinja2 -matplotlib-inline==0.1.7 - # via - # ipykernel - # ipython -mdit-py-plugins==0.4.2 - # via myst-parser -mdurl==0.1.2 - # via markdown-it-py -myst-nb==1.2.0 - # via rocm-docs-core -myst-parser==4.0.1 - # via myst-nb -nbclient==0.10.2 - # via - # jupyter-cache - # myst-nb -nbformat==5.10.4 - # via - # jupyter-cache - # myst-nb - # nbclient -nest-asyncio==1.6.0 - # via ipykernel -packaging==25.0 - # via - # ipykernel - # pydata-sphinx-theme - # sphinx -parso==0.8.4 - # via jedi -pexpect==4.9.0 - # via ipython -platformdirs==4.3.8 - # via jupyter-core -prompt-toolkit==3.0.51 - # via ipython -psutil==7.0.0 - # via ipykernel -ptyprocess==0.7.0 - # via pexpect -pure-eval==0.2.3 - # via stack-data -pycparser==2.22 - # via cffi -pydata-sphinx-theme==0.15.4 - # via - # rocm-docs-core - # sphinx-book-theme -pygithub==2.6.1 - # via rocm-docs-core -pygments==2.19.1 - # via - # accessible-pygments - # ipython - # pydata-sphinx-theme - # sphinx -pyjwt[crypto]==2.10.1 - # via pygithub -pynacl==1.6.2 - # via pygithub -python-dateutil==2.9.0.post0 - # via jupyter-client -pyyaml==6.0.2 - # via - # jupyter-cache - # myst-nb - # myst-parser - # rocm-docs-core - # sphinx-external-toc -pyzmq==26.4.0 - # via - # ipykernel - # jupyter-client -referencing==0.36.2 - # via - # jsonschema - # jsonschema-specifications -requests==2.32.4 - # via - # pygithub - # sphinx -rocm-docs-core==1.31.2 - # via -r requirements.in -rpds-py==0.24.0 - # via - # jsonschema - # referencing -six==1.17.0 - # via python-dateutil -smmap==5.0.2 - # via gitdb -snowballstemmer==3.0.0.1 - # via sphinx -soupsieve==2.7 - # via beautifulsoup4 -sphinx==8.1.3 - # via - # breathe - # myst-nb - # myst-parser - # pydata-sphinx-theme - # rocm-docs-core - # sphinx-book-theme - # sphinx-copybutton - # sphinx-design - # sphinx-external-toc - # sphinx-notfound-page -sphinx-book-theme==1.1.4 - # via rocm-docs-core -sphinx-copybutton==0.5.2 - # via rocm-docs-core -sphinx-design==0.6.1 - # via rocm-docs-core -sphinx-external-toc==1.0.1 - # via rocm-docs-core -sphinx-notfound-page==1.1.0 - # via rocm-docs-core -sphinxcontrib-applehelp==2.0.0 - # via sphinx -sphinxcontrib-devhelp==2.0.0 - # via sphinx -sphinxcontrib-htmlhelp==2.1.0 - # via sphinx -sphinxcontrib-jsmath==1.0.1 - # via sphinx -sphinxcontrib-qthelp==2.0.0 - # via sphinx -sphinxcontrib-serializinghtml==2.0.0 - # via sphinx -sqlalchemy==2.0.40 - # via jupyter-cache -stack-data==0.6.3 - # via ipython -tabulate==0.9.0 - # via jupyter-cache -tomli==2.2.1 - # via sphinx -tornado==6.5.1 - # via - # ipykernel - # jupyter-client -traitlets==5.14.3 - # via - # comm - # ipykernel - # ipython - # jupyter-client - # jupyter-core - # matplotlib-inline - # nbclient - # nbformat -typing-extensions==4.13.2 - # via - # beautifulsoup4 - # ipython - # myst-nb - # pydata-sphinx-theme - # pygithub - # referencing - # sqlalchemy -urllib3==2.6.3 - # via - # pygithub - # requests -wcwidth==0.2.13 - # via prompt-toolkit -wrapt==1.17.2 - # via deprecated -zipp==3.21.0 - # via importlib-metadata From e54bc258e7a41f456685ca1c45764356604bbc9f Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 18 Mar 2026 16:00:54 -0600 Subject: [PATCH 18/40] Fixed a lot of CMake issues --- cmake/AISDocumentation.cmake | 17 +++-------------- docs/sphinx/{_toc.yml => _toc.yml.in} | 0 docs/sphinx/conf.py | 1 + docs/stats_collection.rst | 8 +++----- 4 files changed, 7 insertions(+), 19 deletions(-) rename docs/sphinx/{_toc.yml => _toc.yml.in} (100%) diff --git a/cmake/AISDocumentation.cmake b/cmake/AISDocumentation.cmake index 68787f92..d78a5714 100644 --- a/cmake/AISDocumentation.cmake +++ b/cmake/AISDocumentation.cmake @@ -55,24 +55,13 @@ if(AIS_BUILD_DOCS) "DOXYGEN_XML_DIR=${AIS_DOXYGEN_XML_DIR}" "${Python3_EXECUTABLE}" -m sphinx -b html - -C - -c "${CMAKE_CURRENT_SOURCE_DIR}/docs/sphinx" - "${CMAKE_CURRENT_SOURCE_DIR}/docs" + -c "${HIPFILE_ROOT_PATH}/docs/sphinx" + "${HIPFILE_ROOT_PATH}/docs" "${AIS_SPHINX_BUILD_DIR}" + -v WORKING_DIRECTORY "${AIS_DOC_PATH}" COMMENT "Generating hipFile API documentation with Doxygen + Sphinx (rocm_docs)" VERBATIM ) - # Set the output directory - #set(DOXYGEN_OUT ${AIS_DOC_PATH}) - - # Configure the documentation build - #add_custom_target("doc" - # COMMAND ${DOXYGEN_EXECUTABLE} ${AIS_DOXYFILE} - # WORKING_DIRECTORY ${AIS_DOC_PATH} - # COMMENT "Generating hipFile API documentation with Doxygen" - # VERBATIM - #) - endif() diff --git a/docs/sphinx/_toc.yml b/docs/sphinx/_toc.yml.in similarity index 100% rename from docs/sphinx/_toc.yml rename to docs/sphinx/_toc.yml.in diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index 59382e09..08d425be 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -45,3 +45,4 @@ # Transfer all Sphinx config variables into this module's global scope for sphinx_var in ROCmDocs.SPHINX_VARS: globals()[sphinx_var] = getattr(docs_core, sphinx_var) +extensions.append('sphinx_design') diff --git a/docs/stats_collection.rst b/docs/stats_collection.rst index e9d5e597..5c1b563e 100644 --- a/docs/stats_collection.rst +++ b/docs/stats_collection.rst @@ -4,10 +4,8 @@ Stats Collection Tool Command-line Tool ----------------- ``ais-stats`` can be run two ways: -* ``$ ais-stats -p [-i]`` will collect stats from a running process. - ``-i`` will report immediately rather than wait for the process to exit. -* ``$ ais-stats [args...]`` will launch ```` with the - provided arguments and report the collected stats when it exits. +* ``$ ais-stats -p [-i]`` will collect stats from a running process. ``-i`` will report immediately rather than wait for the process to exit. +* ``$ ais-stats [args...]`` will launch ```` with the provided arguments and report the collected stats when it exits. Configuration ------------- @@ -24,4 +22,4 @@ Value Description Stats Collected --------------- * Basic: Bytes read/written on the fastpath backend -* Basic: Bytes read/written on the fallback backend \ No newline at end of file +* Basic: Bytes read/written on the fallback backend From 7c224d99e3c065bdd320181a0b4ab09cb35d10f9 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 18 Mar 2026 19:35:31 -0600 Subject: [PATCH 19/40] Fix cmakelint issues --- cmake/AISDocumentation.cmake | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cmake/AISDocumentation.cmake b/cmake/AISDocumentation.cmake index d78a5714..17063ae1 100644 --- a/cmake/AISDocumentation.cmake +++ b/cmake/AISDocumentation.cmake @@ -27,10 +27,10 @@ if(AIS_BUILD_DOCS) # Set Doxygen input (pasted into Doxyfile.in) set(AIS_DOXYFILE_INPUT "${HIPFILE_ROOT_PATH}/include") - + # Set the path to the documentation set(AIS_DOC_PATH "${CMAKE_CURRENT_BINARY_DIR}/docs") - + # Set the Doxyfile install location set(AIS_DOXYFILE "${AIS_DOC_PATH}/doxygen/Doxyfile") From ccc7d1e18f184e8aca15bcca49f25de7c51547f7 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 18 Mar 2026 19:38:10 -0600 Subject: [PATCH 20/40] Fix pylint issues --- docs/sphinx/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index 08d425be..a77e2530 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -24,7 +24,7 @@ version = version_number release = version_number external_projects_current_project = "rocshmem" - +extensions = ['sphinx_design'] external_toc_path = "./sphinx/_toc.yml" docs_core = ROCmDocs(left_nav_title) @@ -45,4 +45,3 @@ # Transfer all Sphinx config variables into this module's global scope for sphinx_var in ROCmDocs.SPHINX_VARS: globals()[sphinx_var] = getattr(docs_core, sphinx_var) -extensions.append('sphinx_design') From 397835cfb1dfcfcd92148a8b067fcf9a182b220e Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 18 Mar 2026 21:55:11 -0600 Subject: [PATCH 21/40] Fix quotes on conf.py --- docs/sphinx/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index a77e2530..52c5f78e 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -24,7 +24,7 @@ version = version_number release = version_number external_projects_current_project = "rocshmem" -extensions = ['sphinx_design'] +extensions = ["sphinx_design"] external_toc_path = "./sphinx/_toc.yml" docs_core = ROCmDocs(left_nav_title) From fdba1f089bf05c8dc28dee46164453c3f3580285 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 07:52:19 -0600 Subject: [PATCH 22/40] Install rocm-docs-core via pip in Docker images --- util/docker/DOCKERFILE.ais_ci_rocky | 4 ++++ util/docker/DOCKERFILE.ais_ci_suse | 4 ++++ util/docker/DOCKERFILE.ais_ci_ubuntu | 4 ++++ 3 files changed, 12 insertions(+) diff --git a/util/docker/DOCKERFILE.ais_ci_rocky b/util/docker/DOCKERFILE.ais_ci_rocky index 37a5f391..b6f2109f 100644 --- a/util/docker/DOCKERFILE.ais_ci_rocky +++ b/util/docker/DOCKERFILE.ais_ci_rocky @@ -73,6 +73,10 @@ RUN dnf makecache && \ llvm-devel \ rpm-build +# Install Python packages +pip3 install --upgrade pip +pip3 install rocm-docs-core + # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf /opt/rocm/lib diff --git a/util/docker/DOCKERFILE.ais_ci_suse b/util/docker/DOCKERFILE.ais_ci_suse index 7e766415..bc9f1bca 100644 --- a/util/docker/DOCKERFILE.ais_ci_suse +++ b/util/docker/DOCKERFILE.ais_ci_suse @@ -71,6 +71,10 @@ RUN zypper install -y \ rocm-device-libs \ rpm-build +# Install Python packages +pip3 install --upgrade pip +pip3 install rocm-docs-core + # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf /opt/rocm/lib diff --git a/util/docker/DOCKERFILE.ais_ci_ubuntu b/util/docker/DOCKERFILE.ais_ci_ubuntu index 0696bedb..1a790c34 100644 --- a/util/docker/DOCKERFILE.ais_ci_ubuntu +++ b/util/docker/DOCKERFILE.ais_ci_ubuntu @@ -20,6 +20,10 @@ RUN apt update && \ curl \ gpg +# Install Python packages +pip3 install --upgrade pip +pip3 install rocm-docs-core + # Retrieve ROCm GPG key RUN curl https://repo.radeon.com/rocm/rocm.gpg.key | \ gpg --dearmor >> /etc/apt/keyrings/rocm.gpg From 019a5de87a7d4bf5eeecdf4c7b29b86df2853814 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 07:56:39 -0600 Subject: [PATCH 23/40] pip3 --> pip --- util/docker/DOCKERFILE.ais_ci_rocky | 4 ++-- util/docker/DOCKERFILE.ais_ci_suse | 4 ++-- util/docker/DOCKERFILE.ais_ci_ubuntu | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/util/docker/DOCKERFILE.ais_ci_rocky b/util/docker/DOCKERFILE.ais_ci_rocky index b6f2109f..3fc5a341 100644 --- a/util/docker/DOCKERFILE.ais_ci_rocky +++ b/util/docker/DOCKERFILE.ais_ci_rocky @@ -74,8 +74,8 @@ RUN dnf makecache && \ rpm-build # Install Python packages -pip3 install --upgrade pip -pip3 install rocm-docs-core +pip install --upgrade pip +pip install rocm-docs-core # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf diff --git a/util/docker/DOCKERFILE.ais_ci_suse b/util/docker/DOCKERFILE.ais_ci_suse index bc9f1bca..c3bbfde7 100644 --- a/util/docker/DOCKERFILE.ais_ci_suse +++ b/util/docker/DOCKERFILE.ais_ci_suse @@ -72,8 +72,8 @@ RUN zypper install -y \ rpm-build # Install Python packages -pip3 install --upgrade pip -pip3 install rocm-docs-core +pip install --upgrade pip +pip install rocm-docs-core # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf diff --git a/util/docker/DOCKERFILE.ais_ci_ubuntu b/util/docker/DOCKERFILE.ais_ci_ubuntu index 1a790c34..b8817f20 100644 --- a/util/docker/DOCKERFILE.ais_ci_ubuntu +++ b/util/docker/DOCKERFILE.ais_ci_ubuntu @@ -21,8 +21,8 @@ RUN apt update && \ gpg # Install Python packages -pip3 install --upgrade pip -pip3 install rocm-docs-core +pip install --upgrade pip +pip install rocm-docs-core # Retrieve ROCm GPG key RUN curl https://repo.radeon.com/rocm/rocm.gpg.key | \ From ac7128fad042f8d79c92099e44d837766f001a38 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 08:00:58 -0600 Subject: [PATCH 24/40] Install pip on Ubuntu --- util/docker/DOCKERFILE.ais_ci_ubuntu | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/util/docker/DOCKERFILE.ais_ci_ubuntu b/util/docker/DOCKERFILE.ais_ci_ubuntu index b8817f20..74d90b03 100644 --- a/util/docker/DOCKERFILE.ais_ci_ubuntu +++ b/util/docker/DOCKERFILE.ais_ci_ubuntu @@ -18,11 +18,12 @@ ARG ROCM_PKG_REPO_OVERRIDE RUN apt update && \ apt install -y \ curl \ - gpg + gpg \ + python3-pip # Install Python packages -pip install --upgrade pip -pip install rocm-docs-core +pip3 install --upgrade pip +pip3 install rocm-docs-core # Retrieve ROCm GPG key RUN curl https://repo.radeon.com/rocm/rocm.gpg.key | \ From 74ab83eb916a4da9b5b92af5847555d2fe93514c Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 08:03:18 -0600 Subject: [PATCH 25/40] Add pip to SUSE and Rocky --- util/docker/DOCKERFILE.ais_ci_rocky | 5 +++-- util/docker/DOCKERFILE.ais_ci_suse | 7 +++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/util/docker/DOCKERFILE.ais_ci_rocky b/util/docker/DOCKERFILE.ais_ci_rocky index 3fc5a341..c0d34446 100644 --- a/util/docker/DOCKERFILE.ais_ci_rocky +++ b/util/docker/DOCKERFILE.ais_ci_rocky @@ -71,11 +71,12 @@ RUN dnf makecache && \ hip-devel \ libmount-devel \ llvm-devel \ + python3-pip \ rpm-build # Install Python packages -pip install --upgrade pip -pip install rocm-docs-core +pip3 install --upgrade pip +pip3 install rocm-docs-core # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf diff --git a/util/docker/DOCKERFILE.ais_ci_suse b/util/docker/DOCKERFILE.ais_ci_suse index c3bbfde7..4e30f973 100644 --- a/util/docker/DOCKERFILE.ais_ci_suse +++ b/util/docker/DOCKERFILE.ais_ci_suse @@ -68,12 +68,15 @@ RUN zypper install -y \ hip-devel \ libmount-devel \ llvm19-devel \ + python3-pip \ + python3-setuptools \ + python3-wheel \ rocm-device-libs \ rpm-build # Install Python packages -pip install --upgrade pip -pip install rocm-docs-core +pip3 install --upgrade pip +pip3 install rocm-docs-core # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf From ed0cbd98932c64e6c55da45c7e700bb01405347e Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 08:08:44 -0600 Subject: [PATCH 26/40] pip3 --> python3 -m pip --- util/docker/DOCKERFILE.ais_ci_rocky | 4 ++-- util/docker/DOCKERFILE.ais_ci_suse | 4 ++-- util/docker/DOCKERFILE.ais_ci_ubuntu | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/util/docker/DOCKERFILE.ais_ci_rocky b/util/docker/DOCKERFILE.ais_ci_rocky index c0d34446..89c16ef8 100644 --- a/util/docker/DOCKERFILE.ais_ci_rocky +++ b/util/docker/DOCKERFILE.ais_ci_rocky @@ -75,8 +75,8 @@ RUN dnf makecache && \ rpm-build # Install Python packages -pip3 install --upgrade pip -pip3 install rocm-docs-core +python3 -m pip install --upgrade pip +python3 -m pip install rocm-docs-core # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf diff --git a/util/docker/DOCKERFILE.ais_ci_suse b/util/docker/DOCKERFILE.ais_ci_suse index 4e30f973..285fd2e7 100644 --- a/util/docker/DOCKERFILE.ais_ci_suse +++ b/util/docker/DOCKERFILE.ais_ci_suse @@ -75,8 +75,8 @@ RUN zypper install -y \ rpm-build # Install Python packages -pip3 install --upgrade pip -pip3 install rocm-docs-core +python3 -m pip install --upgrade pip +python3 -m pip install rocm-docs-core # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf diff --git a/util/docker/DOCKERFILE.ais_ci_ubuntu b/util/docker/DOCKERFILE.ais_ci_ubuntu index 74d90b03..3e5e3163 100644 --- a/util/docker/DOCKERFILE.ais_ci_ubuntu +++ b/util/docker/DOCKERFILE.ais_ci_ubuntu @@ -22,8 +22,8 @@ RUN apt update && \ python3-pip # Install Python packages -pip3 install --upgrade pip -pip3 install rocm-docs-core +python3 -m pip install --upgrade pip +python3 -m pip install rocm-docs-core # Retrieve ROCm GPG key RUN curl https://repo.radeon.com/rocm/rocm.gpg.key | \ From f26adc40296fb43455ab874f60e39c5d19cdbb01 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 10:02:51 -0600 Subject: [PATCH 27/40] Apparently we need Python3 --- util/docker/DOCKERFILE.ais_ci_rocky | 1 + util/docker/DOCKERFILE.ais_ci_suse | 1 + util/docker/DOCKERFILE.ais_ci_ubuntu | 1 + 3 files changed, 3 insertions(+) diff --git a/util/docker/DOCKERFILE.ais_ci_rocky b/util/docker/DOCKERFILE.ais_ci_rocky index 89c16ef8..1206e616 100644 --- a/util/docker/DOCKERFILE.ais_ci_rocky +++ b/util/docker/DOCKERFILE.ais_ci_rocky @@ -71,6 +71,7 @@ RUN dnf makecache && \ hip-devel \ libmount-devel \ llvm-devel \ + python3 \ python3-pip \ rpm-build diff --git a/util/docker/DOCKERFILE.ais_ci_suse b/util/docker/DOCKERFILE.ais_ci_suse index 285fd2e7..e2a4654d 100644 --- a/util/docker/DOCKERFILE.ais_ci_suse +++ b/util/docker/DOCKERFILE.ais_ci_suse @@ -68,6 +68,7 @@ RUN zypper install -y \ hip-devel \ libmount-devel \ llvm19-devel \ + python3 \ python3-pip \ python3-setuptools \ python3-wheel \ diff --git a/util/docker/DOCKERFILE.ais_ci_ubuntu b/util/docker/DOCKERFILE.ais_ci_ubuntu index 3e5e3163..7d990b79 100644 --- a/util/docker/DOCKERFILE.ais_ci_ubuntu +++ b/util/docker/DOCKERFILE.ais_ci_ubuntu @@ -19,6 +19,7 @@ RUN apt update && \ apt install -y \ curl \ gpg \ + python3 \ python3-pip # Install Python packages From 97e48a43003361b5d69703346012fff56d4ccfd6 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 10:08:21 -0600 Subject: [PATCH 28/40] Forgot RUN --- util/docker/DOCKERFILE.ais_ci_rocky | 4 ++-- util/docker/DOCKERFILE.ais_ci_suse | 4 ++-- util/docker/DOCKERFILE.ais_ci_ubuntu | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/util/docker/DOCKERFILE.ais_ci_rocky b/util/docker/DOCKERFILE.ais_ci_rocky index 1206e616..bfa424dd 100644 --- a/util/docker/DOCKERFILE.ais_ci_rocky +++ b/util/docker/DOCKERFILE.ais_ci_rocky @@ -76,8 +76,8 @@ RUN dnf makecache && \ rpm-build # Install Python packages -python3 -m pip install --upgrade pip -python3 -m pip install rocm-docs-core +RUN python3 -m pip install --upgrade pip +RUN python3 -m pip install rocm-docs-core # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf diff --git a/util/docker/DOCKERFILE.ais_ci_suse b/util/docker/DOCKERFILE.ais_ci_suse index e2a4654d..2b59975f 100644 --- a/util/docker/DOCKERFILE.ais_ci_suse +++ b/util/docker/DOCKERFILE.ais_ci_suse @@ -76,8 +76,8 @@ RUN zypper install -y \ rpm-build # Install Python packages -python3 -m pip install --upgrade pip -python3 -m pip install rocm-docs-core +RUN python3 -m pip install --upgrade pip +RUN python3 -m pip install rocm-docs-core # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf diff --git a/util/docker/DOCKERFILE.ais_ci_ubuntu b/util/docker/DOCKERFILE.ais_ci_ubuntu index 7d990b79..72267f45 100644 --- a/util/docker/DOCKERFILE.ais_ci_ubuntu +++ b/util/docker/DOCKERFILE.ais_ci_ubuntu @@ -23,8 +23,8 @@ RUN apt update && \ python3-pip # Install Python packages -python3 -m pip install --upgrade pip -python3 -m pip install rocm-docs-core +RUN python3 -m pip install --upgrade pip +RUN python3 -m pip install rocm-docs-core # Retrieve ROCm GPG key RUN curl https://repo.radeon.com/rocm/rocm.gpg.key | \ From 7a1bc942bbc4e72eeaa5c9ba4dc033d3c08f1dd7 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 10:22:15 -0600 Subject: [PATCH 29/40] Yet another try at the right dependencies --- util/docker/DOCKERFILE.ais_ci_rocky | 7 +++++-- util/docker/DOCKERFILE.ais_ci_suse | 9 +++++---- util/docker/DOCKERFILE.ais_ci_ubuntu | 17 ++++++++++------- 3 files changed, 20 insertions(+), 13 deletions(-) diff --git a/util/docker/DOCKERFILE.ais_ci_rocky b/util/docker/DOCKERFILE.ais_ci_rocky index bfa424dd..ed03048d 100644 --- a/util/docker/DOCKERFILE.ais_ci_rocky +++ b/util/docker/DOCKERFILE.ais_ci_rocky @@ -73,11 +73,14 @@ RUN dnf makecache && \ llvm-devel \ python3 \ python3-pip \ + rocm-docs-core \ rpm-build # Install Python packages -RUN python3 -m pip install --upgrade pip -RUN python3 -m pip install rocm-docs-core +RUN pip3 install \ + sphinx \ + breathe \ + sphinx-rtd-theme # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf diff --git a/util/docker/DOCKERFILE.ais_ci_suse b/util/docker/DOCKERFILE.ais_ci_suse index 2b59975f..97747456 100644 --- a/util/docker/DOCKERFILE.ais_ci_suse +++ b/util/docker/DOCKERFILE.ais_ci_suse @@ -70,14 +70,15 @@ RUN zypper install -y \ llvm19-devel \ python3 \ python3-pip \ - python3-setuptools \ - python3-wheel \ rocm-device-libs \ + rocm-docs-core \ rpm-build # Install Python packages -RUN python3 -m pip install --upgrade pip -RUN python3 -m pip install rocm-docs-core +RUN pip3 install \ + sphinx \ + breathe \ + sphinx-rtd-theme # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf diff --git a/util/docker/DOCKERFILE.ais_ci_ubuntu b/util/docker/DOCKERFILE.ais_ci_ubuntu index 72267f45..3d67d2f3 100644 --- a/util/docker/DOCKERFILE.ais_ci_ubuntu +++ b/util/docker/DOCKERFILE.ais_ci_ubuntu @@ -18,13 +18,7 @@ ARG ROCM_PKG_REPO_OVERRIDE RUN apt update && \ apt install -y \ curl \ - gpg \ - python3 \ - python3-pip - -# Install Python packages -RUN python3 -m pip install --upgrade pip -RUN python3 -m pip install rocm-docs-core + gpg # Retrieve ROCm GPG key RUN curl https://repo.radeon.com/rocm/rocm.gpg.key | \ @@ -57,8 +51,17 @@ RUN apt update && \ libboost-program-options-dev \ libmount-dev \ llvm-dev \ + python3 \ + python3-pip \ + rocm-docs-core \ rocm-llvm-dev +# Install Python packages +RUN pip3 install \ + sphinx \ + breathe \ + sphinx-rtd-theme + # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf /opt/rocm/lib From e2f9da3426c9aba67d7b7879d2a40f8bc03b48c2 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 10:41:21 -0600 Subject: [PATCH 30/40] Add debug output to Ubuntu --- util/docker/DOCKERFILE.ais_ci_ubuntu | 3 +++ 1 file changed, 3 insertions(+) diff --git a/util/docker/DOCKERFILE.ais_ci_ubuntu b/util/docker/DOCKERFILE.ais_ci_ubuntu index 3d67d2f3..71b9d6e5 100644 --- a/util/docker/DOCKERFILE.ais_ci_ubuntu +++ b/util/docker/DOCKERFILE.ais_ci_ubuntu @@ -39,6 +39,9 @@ Pin: release o=repo.radeon.com Pin-Priority: 600 EOF +#Debug +RUN apt-cache search rocm-docs-core + # Development Dependencies RUN apt update && \ apt install -y \ From 0cd74f16d4bb403a23e58523971219a24e06d17f Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 11:52:30 -0600 Subject: [PATCH 31/40] Docker Python setup should work now --- util/docker/DOCKERFILE.ais_ci_rocky | 9 ++++++--- util/docker/DOCKERFILE.ais_ci_suse | 9 ++++++--- util/docker/DOCKERFILE.ais_ci_ubuntu | 13 ++++++------- 3 files changed, 18 insertions(+), 13 deletions(-) diff --git a/util/docker/DOCKERFILE.ais_ci_rocky b/util/docker/DOCKERFILE.ais_ci_rocky index ed03048d..fb15185d 100644 --- a/util/docker/DOCKERFILE.ais_ci_rocky +++ b/util/docker/DOCKERFILE.ais_ci_rocky @@ -73,14 +73,17 @@ RUN dnf makecache && \ llvm-devel \ python3 \ python3-pip \ + python3-venv \ rocm-docs-core \ rpm-build -# Install Python packages -RUN pip3 install \ +# Install Python packages (don't source venv/bin/activate) +RUN python3 -m venv ~/venv +RUN ~/venv/bin/pip3 install \ sphinx \ breathe \ - sphinx-rtd-theme + sphinx-rtd-theme \ + rocm-docs-core # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf diff --git a/util/docker/DOCKERFILE.ais_ci_suse b/util/docker/DOCKERFILE.ais_ci_suse index 97747456..42031cb8 100644 --- a/util/docker/DOCKERFILE.ais_ci_suse +++ b/util/docker/DOCKERFILE.ais_ci_suse @@ -70,15 +70,18 @@ RUN zypper install -y \ llvm19-devel \ python3 \ python3-pip \ + python3-venv \ rocm-device-libs \ rocm-docs-core \ rpm-build -# Install Python packages -RUN pip3 install \ +# Install Python packages (don't source venv/bin/activate) +RUN python3 -m venv ~/venv +RUN ~/venv/bin/pip3 install \ sphinx \ breathe \ - sphinx-rtd-theme + sphinx-rtd-theme \ + rocm-docs-core # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf diff --git a/util/docker/DOCKERFILE.ais_ci_ubuntu b/util/docker/DOCKERFILE.ais_ci_ubuntu index 71b9d6e5..25501fbf 100644 --- a/util/docker/DOCKERFILE.ais_ci_ubuntu +++ b/util/docker/DOCKERFILE.ais_ci_ubuntu @@ -39,9 +39,6 @@ Pin: release o=repo.radeon.com Pin-Priority: 600 EOF -#Debug -RUN apt-cache search rocm-docs-core - # Development Dependencies RUN apt update && \ apt install -y \ @@ -56,14 +53,16 @@ RUN apt update && \ llvm-dev \ python3 \ python3-pip \ - rocm-docs-core \ + python3-venv \ rocm-llvm-dev -# Install Python packages -RUN pip3 install \ +# Install Python packages (don't source venv/bin/activate) +RUN python3 -m venv ~/venv +RUN ~/venv/bin/pip3 install \ sphinx \ breathe \ - sphinx-rtd-theme + sphinx-rtd-theme \ + rocm-docs-core # Configure system linker for ROCm RUN cat < /etc/ld.so.conf.d/rocm.conf From 0e86476ad4ea3327229f13372c06fca7ef4eac94 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 11:56:05 -0600 Subject: [PATCH 32/40] Add venv to CI --- .github/workflows/build-ais.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/build-ais.yml b/.github/workflows/build-ais.yml index c86a2e9a..acdc6328 100644 --- a/.github/workflows/build-ais.yml +++ b/.github/workflows/build-ais.yml @@ -137,6 +137,7 @@ jobs: -w /ais/hipFile/build \ "${AIS_CONTAINER_NAME}" \ /bin/bash -c ' + source ~/venv/bin/activate export CPACK_DEBIAN_PACKAGE_RELEASE="${JOB_DESIGNATOR}${SLES_BUILD_ID_PREFIX}${BUILD_ID}~$(source /etc/os-release && echo ${VERSION_ID})" export CPACK_RPM_PACKAGE_RELEASE="${JOB_DESIGNATOR}${SLES_BUILD_ID_PREFIX}${BUILD_ID}" cmake \ From ff9c648cb2cfb35d3a5731fbcd21e1aef328e784 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 12:00:21 -0600 Subject: [PATCH 33/40] Remove rocm-docs-core from list of apt packages --- util/docker/DOCKERFILE.ais_ci_rocky | 1 - util/docker/DOCKERFILE.ais_ci_suse | 1 - 2 files changed, 2 deletions(-) diff --git a/util/docker/DOCKERFILE.ais_ci_rocky b/util/docker/DOCKERFILE.ais_ci_rocky index fb15185d..06203146 100644 --- a/util/docker/DOCKERFILE.ais_ci_rocky +++ b/util/docker/DOCKERFILE.ais_ci_rocky @@ -74,7 +74,6 @@ RUN dnf makecache && \ python3 \ python3-pip \ python3-venv \ - rocm-docs-core \ rpm-build # Install Python packages (don't source venv/bin/activate) diff --git a/util/docker/DOCKERFILE.ais_ci_suse b/util/docker/DOCKERFILE.ais_ci_suse index 42031cb8..ca3794c6 100644 --- a/util/docker/DOCKERFILE.ais_ci_suse +++ b/util/docker/DOCKERFILE.ais_ci_suse @@ -72,7 +72,6 @@ RUN zypper install -y \ python3-pip \ python3-venv \ rocm-device-libs \ - rocm-docs-core \ rpm-build # Install Python packages (don't source venv/bin/activate) From 53b493c55beee5484c8e3b3d7ca3327bd7fac136 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 14:02:45 -0600 Subject: [PATCH 34/40] Fix Python configs --- .github/workflows/build-ais.yml | 2 +- util/docker/DOCKERFILE.ais_ci_rocky | 5 ++--- util/docker/DOCKERFILE.ais_ci_suse | 11 ++++++----- util/docker/DOCKERFILE.ais_ci_ubuntu | 4 ++-- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.github/workflows/build-ais.yml b/.github/workflows/build-ais.yml index acdc6328..a9a677de 100644 --- a/.github/workflows/build-ais.yml +++ b/.github/workflows/build-ais.yml @@ -137,7 +137,7 @@ jobs: -w /ais/hipFile/build \ "${AIS_CONTAINER_NAME}" \ /bin/bash -c ' - source ~/venv/bin/activate + source /opt/venv/bin/activate export CPACK_DEBIAN_PACKAGE_RELEASE="${JOB_DESIGNATOR}${SLES_BUILD_ID_PREFIX}${BUILD_ID}~$(source /etc/os-release && echo ${VERSION_ID})" export CPACK_RPM_PACKAGE_RELEASE="${JOB_DESIGNATOR}${SLES_BUILD_ID_PREFIX}${BUILD_ID}" cmake \ diff --git a/util/docker/DOCKERFILE.ais_ci_rocky b/util/docker/DOCKERFILE.ais_ci_rocky index 06203146..9d9d38f4 100644 --- a/util/docker/DOCKERFILE.ais_ci_rocky +++ b/util/docker/DOCKERFILE.ais_ci_rocky @@ -73,12 +73,11 @@ RUN dnf makecache && \ llvm-devel \ python3 \ python3-pip \ - python3-venv \ rpm-build # Install Python packages (don't source venv/bin/activate) -RUN python3 -m venv ~/venv -RUN ~/venv/bin/pip3 install \ +RUN python3 -m venv /opt/venv +RUN /opt/venv/bin/pip3 install \ sphinx \ breathe \ sphinx-rtd-theme \ diff --git a/util/docker/DOCKERFILE.ais_ci_suse b/util/docker/DOCKERFILE.ais_ci_suse index ca3794c6..c654c9e6 100644 --- a/util/docker/DOCKERFILE.ais_ci_suse +++ b/util/docker/DOCKERFILE.ais_ci_suse @@ -68,15 +68,16 @@ RUN zypper install -y \ hip-devel \ libmount-devel \ llvm19-devel \ - python3 \ - python3-pip \ - python3-venv \ + python312 \ + python312-pip \ rocm-device-libs \ rpm-build # Install Python packages (don't source venv/bin/activate) -RUN python3 -m venv ~/venv -RUN ~/venv/bin/pip3 install \ +RUN python3.12 --version +RUN python3.12 -m venv /opt/venv +RUN /opt/venv/bin/pip3 install --upgrade pip +RUN /opt/venv/bin/pip3 install \ sphinx \ breathe \ sphinx-rtd-theme \ diff --git a/util/docker/DOCKERFILE.ais_ci_ubuntu b/util/docker/DOCKERFILE.ais_ci_ubuntu index 25501fbf..288cfe20 100644 --- a/util/docker/DOCKERFILE.ais_ci_ubuntu +++ b/util/docker/DOCKERFILE.ais_ci_ubuntu @@ -57,8 +57,8 @@ RUN apt update && \ rocm-llvm-dev # Install Python packages (don't source venv/bin/activate) -RUN python3 -m venv ~/venv -RUN ~/venv/bin/pip3 install \ +RUN python3 -m venv /opt/venv +RUN /opt/venv/bin/pip3 install \ sphinx \ breathe \ sphinx-rtd-theme \ From 53b81bdf8df4f6f4e4ff4845f514fda2e35b2130 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 16:25:51 -0600 Subject: [PATCH 35/40] Copy conf.py and _toc.yml.in to build directory Avoids dirtying the source directory --- cmake/AISDocumentation.cmake | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/cmake/AISDocumentation.cmake b/cmake/AISDocumentation.cmake index 17063ae1..2cbb0d84 100644 --- a/cmake/AISDocumentation.cmake +++ b/cmake/AISDocumentation.cmake @@ -31,6 +31,12 @@ if(AIS_BUILD_DOCS) # Set the path to the documentation set(AIS_DOC_PATH "${CMAKE_CURRENT_BINARY_DIR}/docs") + ########### + # Doxygen # + ########### + + # The Doxygen HTML, XML, etc. goes in docs/doxygen/ + # Set the Doxyfile install location set(AIS_DOXYFILE "${AIS_DOC_PATH}/doxygen/Doxyfile") @@ -40,8 +46,24 @@ if(AIS_BUILD_DOCS) # Create the Doxyfile from the input file configure_file("docs/doxygen/Doxyfile.in" ${AIS_DOXYFILE}) + ########## + # Sphinx # + ########## + + # The Sphinx HTML, XML, etc. goes in docs/sphinx/ + + # Set the target for the config file and toc file + set(AIS_SPHINX_CONF_FILE "${AIS_DOC_PATH}/sphinx/conf.py") + set(AIS_SPHINX_TOC_FILE "${AIS_DOC_PATH}/sphinx/_toc.yml.in") + # Sphinx HTML output dir - set(AIS_SPHINX_BUILD_DIR "${AIS_DOC_PATH}/html") + set(AIS_SPHINX_BUILD_DIR "${AIS_DOC_PATH}/sphinx/html") + + # Copy conf.py and the table of contents file + # Need to do this so the toc file doesn't dirty the repo + # _toc.yml.in is transformed by rocm_docs, not CMake + configure_file("docs/sphinx/conf.py" ${AIS_SPHINX_CONF_FILE} COPYONLY) + configure_file("docs/sphinx/_toc.yml.in" ${AIS_SPHINX_TOC_FILE} COPYONLY) # Build docs: Doxygen first, then Sphinx (which pulls in rocm_docs via conf.py) add_custom_target(doc @@ -55,7 +77,7 @@ if(AIS_BUILD_DOCS) "DOXYGEN_XML_DIR=${AIS_DOXYGEN_XML_DIR}" "${Python3_EXECUTABLE}" -m sphinx -b html - -c "${HIPFILE_ROOT_PATH}/docs/sphinx" + -c "${AIS_DOC_PATH}/sphinx" "${HIPFILE_ROOT_PATH}/docs" "${AIS_SPHINX_BUILD_DIR}" -v From c6563f180e33550418e8d32fd473601a050b89a7 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 17:34:29 -0600 Subject: [PATCH 36/40] Add a README to the docs directory --- INSTALL.md | 20 +++++--------------- docs/README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 15 deletions(-) create mode 100644 docs/README.md diff --git a/INSTALL.md b/INSTALL.md index b2e9cc97..35485392 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -116,6 +116,9 @@ sudo systemctl reboot * `libmount-dev` (Debian/Ubuntu) * `libmount-devel` (RHEL/Fedora/openSUSE) +Please the the README.md file in the docs directory for requirements +for building the documentation. + ### Configure You do not need to set the `HIP_PLATFORM` environment variable, as @@ -126,7 +129,7 @@ that will be set by CMake. Options |Option|Default|Purpose| |------|-------|-------| -|AIS\_BUILD\_DOCS|OFF|Build API documentation (requires Doxygen)| +|AIS\_BUILD\_DOCS|OFF|Build API documentation (see `docs/README.md`)| |AIS\_INSTALL\_EXAMPLES|ON|Install example programs| |AIS\_USE\_CLANG\_TIDY|OFF|Run the `clang-tidy` tool (clang only)| |AIS\_USE\_CODE\_COVERAGE|OFF|Generate code coverage information when tests are run (clang only)| @@ -191,18 +194,5 @@ The results will be wrote to `/build`, in the `coverage-report.txt` and `coverage-lines.txt` files. ### Documentation -The API documentation is built using Doxygen. To build it, use the -`AIS_BUILD_DOCS` option. This will build the documentation for any -libraries that have been configured. As a special case, configuring -the documentation without any library will build the documentation -for BOTH libraries, allowing for a docs-only build. - -The documentation will be built with the libraries and appear in -`docs/(hip|roc)file`. We build HTML, XML, and LaTeX docs. If you -want a pdf, run `make pdf` in the `latex` directory, which will -create a file named refman.pdf that you can rename. - -If you want to build the docs without compiling the libraries, -you can just build the `doc` target (if you've set `AIS_BUILD_DOCS`): - `cmake --build . --target doc` +See `docs/README.md` diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..a6404b11 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,45 @@ +# hipFile Documentation + +hipFile is documented using Doxygen markup in the public header +files and Sphinx .rst files. + +## Building the Documentation + +### Requirements + +* CMake >= 3.21 +* Doxygen (we use 1.9.8, other versions are untested) +* Python 3.12 (earlier versions might work but are untested) +* The following Python packages: + * breathe + * rocm-docs-core + * sphinx + * sphinx-rtd-theme + +### Generation + +Building the documentation is done via CMake by turning on the docs +option (which is off by default). + + `cmake -DAIS_BUILD_DOCS=ON ` + +You can then build the `doc` target. + + `cmake --build . --target doc` + +The documentation will be in the `docs` subdirectory of the build +directory. + +## Adding to the Documentation + +### API Documentation (Doxygen) + +* Make your markup look like the rest of the file +* Doxygen macros can be found in `docs/doxygen/Doxyfile.in` +* All public API types, functions, etc. MUST have Doxygen markup + +### Other Documentation (Sphinx) + +All other documentation goes in Sphinx .rst documents. API-specific documentation +belongs in `docs/API` and other documentation goes in `docs`. Be sure to update +`sphinx/_toc.yml.in` if you add any new files. From 6acde4da37b9e10d829359769296f9fe1d76e85c Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 22:27:31 -0600 Subject: [PATCH 37/40] Update docs/README.md --- docs/README.md | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index a6404b11..bebce1f8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,6 +5,22 @@ files and Sphinx .rst files. ## Building the Documentation +hipFile can generate two documentation products: + +1. API documentation +2. Sphinx HTML documentation (includes #1) + +API documentation is generated from Doxygen and limited to markup +in the header files. This will generate HTML, XML, and LaTeX output. +The LaTeX can be used to create a pdf document. + +The Sphinx documentation incorporates the Doxygen API markup and +adds reStructured text file content to generate HTML documentation +for the web. + +The documentation CMake target currently builds both. There is +no way to select "just Doxygen". + ### Requirements * CMake >= 3.21 @@ -16,6 +32,8 @@ files and Sphinx .rst files. * sphinx * sphinx-rtd-theme +If you want to build a pdf, you will need LaTeX and pdflatex. + ### Generation Building the documentation is done via CMake by turning on the docs @@ -28,7 +46,19 @@ You can then build the `doc` target. `cmake --build . --target doc` The documentation will be in the `docs` subdirectory of the build -directory. +directory: + +``` + ├── doxygen + │   ├── html + │   ├── latex + │   └── xml + └── sphinx + └── html +``` + +To generate a pdf, navigate to doxygen/latex and run `make pdf` to +generate a pdf named `refman.pdf`. ## Adding to the Documentation From 5d41a9f8c7a8647966ace8382f684ebfc38347e3 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 22:29:23 -0600 Subject: [PATCH 38/40] Add a blank line before bulleted list --- docs/stats_collection.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/stats_collection.rst b/docs/stats_collection.rst index 5c1b563e..f8a9782b 100644 --- a/docs/stats_collection.rst +++ b/docs/stats_collection.rst @@ -4,6 +4,7 @@ Stats Collection Tool Command-line Tool ----------------- ``ais-stats`` can be run two ways: + * ``$ ais-stats -p [-i]`` will collect stats from a running process. ``-i`` will report immediately rather than wait for the process to exit. * ``$ ais-stats [args...]`` will launch ```` with the provided arguments and report the collected stats when it exits. From c46bd65fb2ea9e79ef0c97070c829cbbff2daf8e Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 22:31:37 -0600 Subject: [PATCH 39/40] Update CHANGELOG.md --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index a13a12b6..b979017e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ * Added check in the Fastpath/AIS backend to ensure the HIP Runtime is initialized. This avoids causing a segfault in the HIP Runtime. * The default CMake build type was changed from `Debug` to `RelWithDebInfo` * Added file type and file system validation in Fastpath. Fastpath will only accept IO targeting block devices or regular files backed by xfs or ext4 with ordered journaling mode. Other file systems can be explicitly allowed via the `HIPFILE_UNSUPPORTED_FILE_SYSTEMS` environment variable. +* The docs directory has been reorganized and `AIS_BUILD_DOCS` will now generate Sphinx output for the web. ### Removed * The rocFile library has been completely removed and the code is now a part of hipFile. From 172aa0979b7175432a83190e98cea9bf00e91bc7 Mon Sep 17 00:00:00 2001 From: Dana Robinson Date: Wed, 25 Mar 2026 23:57:49 -0600 Subject: [PATCH 40/40] Add Sphinx LaTeX output --- cmake/AISDocumentation.cmake | 14 +++++++++++++- docs/README.md | 6 +++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/cmake/AISDocumentation.cmake b/cmake/AISDocumentation.cmake index 2cbb0d84..2bb9596d 100644 --- a/cmake/AISDocumentation.cmake +++ b/cmake/AISDocumentation.cmake @@ -69,7 +69,7 @@ if(AIS_BUILD_DOCS) add_custom_target(doc # Step 1: Run Doxygen to produce XML for Breathe COMMAND "${DOXYGEN_EXECUTABLE}" "${AIS_DOXYFILE}" - # Step 2: Run Sphinx, injecting the Doxygen paths via environment + # Step 2: Run Sphinx (html), injecting the Doxygen paths via environment COMMAND ${CMAKE_COMMAND} -E env "DOXYFILE_PATH=${AIS_DOXYFILE}" @@ -81,6 +81,18 @@ if(AIS_BUILD_DOCS) "${HIPFILE_ROOT_PATH}/docs" "${AIS_SPHINX_BUILD_DIR}" -v + # Step 3: Run Sphinx (LaTeX), injecting the Doxygen paths via environment + COMMAND + ${CMAKE_COMMAND} -E env + "DOXYFILE_PATH=${AIS_DOXYFILE}" + "DOXYGEN_ROOT=${AIS_DOC_PATH}/doxygen" + "DOXYGEN_XML_DIR=${AIS_DOXYGEN_XML_DIR}" + "${Python3_EXECUTABLE}" -m sphinx + -b latex + -c "${AIS_DOC_PATH}/sphinx" + "${HIPFILE_ROOT_PATH}/docs" + "${AIS_SPHINX_BUILD_DIR}" + -v WORKING_DIRECTORY "${AIS_DOC_PATH}" COMMENT "Generating hipFile API documentation with Doxygen + Sphinx (rocm_docs)" VERBATIM diff --git a/docs/README.md b/docs/README.md index bebce1f8..6b156561 100644 --- a/docs/README.md +++ b/docs/README.md @@ -57,9 +57,13 @@ directory: └── html ``` -To generate a pdf, navigate to doxygen/latex and run `make pdf` to +To generate a pdf for the API docs, navigate to `doxygen/latex` and run `make pdf` to generate a pdf named `refman.pdf`. +To generate a pdf for the Sphinx docs, navigate to `sphinx/html` and run `make` in +the directory. This will generate a pdf named `rocshmem.pdf` (we are stealing their +configs until `rocm-docs-core` is updated). + ## Adding to the Documentation ### API Documentation (Doxygen)