Add Sphinx support to documentation

.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-core
 
       - name: Lint all Python files
         run: |

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

cmake/AISDocumentation.cmake

@@ -13,6 +13,17 @@ 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")
@@ -21,19 +32,35 @@ if(AIS_BUILD_DOCS)
     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/Doxyfile.in" ${AIS_DOXYFILE})
+    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 "${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
     )
 

docs/Doxyfile.in → 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

docs/hipify.rst

@@ -0,0 +1,2 @@
+hipify
+======

docs/index.rst

@@ -0,0 +1,43 @@
+.. meta::
+  :description: hipFile does hipFile stuff
+  :keywords: hipFile, ROCm, storage, library, API, DMA
+
+*********************
+hipFile documentation
+*********************
+
+hipFile introduction goes here. For more information, see :doc:`introduction`.
+
+The hipFile public repository is located at `<https://github.com/ROCm/hipFile>`_.
+
+.. 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>`
+      * :doc:`Collecting statistics <./stats_collection>`
+
+  .. 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 <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
+
+You can find licensing information on the
+`Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.

docs/sphinx/_toc.yml.in

@@ -0,0 +1,45 @@
+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
+  - file: stats_collection.rst
+    title: Collecting statistics
+
+- 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 operations
+  - file: api/batch.rst
+    title: Batch operations
+  - file: api/rdma.rst
+    title: RDMA
+  - file: api/misc_api.rst
+    title: Other

docs/sphinx/conf.py

@@ -0,0 +1,47 @@
+# 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
+
+# Pylint is NOT happy with the naming scheme ROCm chose
+# pylint: disable=invalid-name
+
+"""This file is for configuring hipFile documentation"""
+
+import os
+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 = "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
+external_projects_current_project = "rocshmem"
+extensions = ["sphinx_design"]
+external_toc_path = "./sphinx/_toc.yml"
+
+docs_core = ROCmDocs(left_nav_title)
+
+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()
+
+# 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)

docs/stats_collection.rst

@@ -4,10 +4,8 @@ Stats Collection Tool
 Command-line Tool
 -----------------
 ``ais-stats`` can be run two ways:
-* ``$ ais-stats -p <PID> [-i]`` will collect stats from a running process.
-  ``-i`` will report immediately rather than wait for the process to exit.
-* ``$ ais-stats <program> [args...]`` will launch ``<program>`` with the
-  provided arguments and report the collected stats when it exits.
+* ``$ ais-stats -p <PID> [-i]`` will collect stats from a running process. ``-i`` will report immediately rather than wait for the process to exit.
+* ``$ ais-stats <program> [args...]`` will launch ``<program>`` 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
+* Basic: Bytes read/written on the fallback backend