Add Sphinx support to documentation

[derobins]

WIP

AIHIPFILE-41

[Copilot]

Pull request overview

This PR adds initial Sphinx/Read the Docs scaffolding for hipFile documentation, including pinned Python doc dependencies, a Sphinx conf.py, a JupyterBook-style TOC, and a Doxygen configuration intended to feed API reference pages.

Changes:

• Add Read the Docs config and Sphinx configuration (.readthedocs.yaml, docs/conf.py).
• Add doc build inputs: Doxygen template, external TOC, and pinned Sphinx dependency set (docs/doxygen/Doxyfile.in, docs/sphinx/*).
• Add initial RST content for the docs landing page and API sections (docs/index.rst, docs/api/*.rst, etc.).

Reviewed changes

Copilot reviewed 8 out of 17 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
docs/sphinx/requirements.txt	Pinned, compiled Python dependency set for building docs.
docs/sphinx/requirements.in	Source input for pip-compile (rocm-docs-core pin).
docs/sphinx/_toc.yml.in	External TOC definition for Sphinx (currently committed as .in).
docs/index.rst	New docs landing page and navigation grid.
docs/hipify.rst	Stub page for hipify docs section.
docs/doxygen/Doxyfile.in	Doxygen configuration template intended for API XML generation.
docs/conf.py	Sphinx configuration using rocm_docs helpers and Doxygen invocation.
docs/api/async.rst	Async API page (currently notes unsupported).
docs/api/batch.rst	Batch API page (currently notes unsupported).
docs/api/core.rst	Core API and versioning documentation.
docs/api/driver.rst	Driver API documentation.
docs/api/errors.rst	Error handling documentation.
docs/api/file.rst	File handle/buffer/IO operations documentation.
docs/api/misc_api.rst	Placeholder “Misc Notes” page.
docs/api/rdma.rst	RDMA page (currently notes unsupported).
cmake/AISDocumentation.cmake	Update Doxygen template path for CMake-driven doc builds.
.readthedocs.yaml	Read the Docs build configuration pointing at Sphinx config + requirements.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Adds an initial Sphinx-based documentation build (integrated with ROCm’s rocm-docs-core) and wires it into CI/container images, alongside a new set of .rst pages for the hipFile docs.

Changes:

• Install Python + Sphinx toolchain (Sphinx/Breathe/rocm-docs-core) into the CI Docker images and activate the venv during the GitHub Actions build.
• Add Sphinx configuration + TOC and introduce/expand multiple documentation pages (index, API reference sections, etc.).
• Update the docs CMake flow to run Doxygen then Sphinx, and add a Read the Docs config.

Reviewed changes

Copilot reviewed 13 out of 21 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
util/docker/DOCKERFILE.ais_ci_ubuntu	Installs Python + creates venv with Sphinx-related packages for CI builds.
util/docker/DOCKERFILE.ais_ci_suse	Same as above for SUSE; uses Python 3.12 and upgrades pip.
util/docker/DOCKERFILE.ais_ci_rocky	Same as above for Rocky Linux.
.github/workflows/build-ais.yml	Activates the venv so CMake can find Python deps while building docs in CI.
.github/workflows/pylint.yml	Installs rocm-docs-core so pylint can analyze Sphinx config importing it.
cmake/AISDocumentation.cmake	Adds Sphinx build steps (Doxygen XML + Sphinx HTML) and checks for rocm_docs.
docs/doxygen/Doxyfile.in	Redirects Doxygen output under the build docs directory.
docs/sphinx/conf.py	Adds Sphinx config using rocm_docs + Doxygen environment wiring.
docs/sphinx/_toc.yml.in	Adds ROCm docs-style TOC definition for the Sphinx site structure.
.readthedocs.yaml	Introduces RTD config intending to build the docs on Read the Docs.
docs/index.rst	Adds a new documentation landing page using sphinx-design grids.
docs/stats_collection.rst	Adjusts formatting/content for the stats collection tool page.
docs/hipify.rst	Adds a stub page for hipify docs.
docs/api/errors.rst	Adds error-handling documentation.
docs/api/core.rst	Adds core/API versioning documentation.
docs/api/driver.rst	Adds driver API documentation.
docs/api/file.rst	Adds file handle/buffer/I/O documentation.
docs/api/async.rst	Adds async API status page (currently unsupported).
docs/api/batch.rst	Adds batch API status page (currently unsupported).
docs/api/rdma.rst	Adds RDMA API status page (currently unsupported).
docs/api/misc_api.rst	Adds miscellaneous notes page.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Read the Docs is configured to use docs/conf.py, but this repo only contains docs/sphinx/conf.py (and the CMake build copies that into the build tree). As-is, RTD builds will fail to start because the configured Sphinx conf.py path does not exist. Update the RTD config to point at the actual Sphinx config file (or add a docs/conf.py shim that delegates to docs/sphinx/conf.py).

Suggested change

	configuration: docs/conf.py
	configuration: docs/sphinx/conf.py

[Copilot]

.readthedocs.yaml installs from docs/sphinx/requirements.txt, but that file isn't present in the repository. RTD builds will fail during dependency installation unless you add this requirements file or change the python.install section to install the needed packages another way.

Suggested change

	- requirements: docs/sphinx/requirements.txt
	- method: pip
	path: .

[Copilot]

external_toc_path points to ./sphinx/_toc.yml, but the repo only adds _toc.yml.in (and the CMake build also copies _toc.yml.in). Unless something generates _toc.yml at build time in the expected location, Sphinx/rocm_docs won't be able to find the TOC. Make external_toc_path reference the file that actually exists (or ensure _toc.yml is generated/copied before Sphinx runs).

Suggested change

	external_toc_path = "./sphinx/_toc.yml"
	external_toc_path = "./sphinx/_toc.yml.in"

[kurtmcmillan]

Maybe add a comment why hipFile is masquerading as rocSHMEM.

[riley-dixon]

Feel free to auto-resolve these comments.

[riley-dixon]

You may wish to consider listing these in a requirements.txt file if they are going to be shared across CI images.
That file could exist in the docker directory as rocm-docs-requirements.txt and then used via pip3 install -r rocm-docs-requirements.txt. You would just need to COPY the file into the container first.

[derobins]

That's a good idea. We could also then turn caching on.

[riley-dixon]

Capitalize Documentation?

[riley-dixon]

Was this going to be replaced later?

[derobins]

Yes. This is still fundamentally a draft. I just flipped it to normal to see what Copilot was going to complain about.

[riley-dixon]

Same comment as https://github.com/ROCm/hipFile/pull/224/changes#r2996045281 in case this was not intentional. Feel free to auto-resolve.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 24 changed files in this pull request and generated 8 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The new sentence has a grammatical error ("Please the the") and is missing the verb (likely "Please see"). Also consider linking directly to docs/README.md to avoid ambiguity.

Suggested change

	Please the the README.md file in the docs directory for requirements
	for building the documentation.
	Please see docs/README.md for requirements for building the documentation.

[Copilot]

The Sphinx LaTeX build is currently writing into the HTML output directory (${AIS_SPHINX_BUILD_DIR}), which will overwrite/mix outputs and makes it impossible to run make for a PDF from the expected LaTeX build dir. Use a dedicated LaTeX output directory (e.g., ${AIS_DOC_PATH}/sphinx/latex) for the -b latex invocation.

[Copilot]

The comment says this block verifies "Sphinx + rocm_docs" are available, but the code only checks import rocm_docs. Either extend the check to also validate Sphinx/Breathe imports, or update the comment to match what’s actually being verified.

[Copilot]

The Read the Docs config points to docs/conf.py, but this repo’s Sphinx config is under docs/sphinx/conf.py (and docs/sphinx is the only Sphinx config dir present). As written, RTD will fail to find the configuration file.

Suggested change

	configuration: docs/conf.py
	configuration: docs/sphinx/conf.py

[Copilot]

This config pins Read the Docs to Python 3.10, but docs/README.md states Python 3.12 is required/expected. Align the documented requirement with what RTD uses (or update RTD to use 3.12 if that’s the actual requirement).

Suggested change

	python: "3.10"
	python: "3.12"

[Copilot]

The PDF generation instructions for Sphinx are inconsistent with how Sphinx typically outputs LaTeX (and with the CMake target invoking -b latex). You generally need to run make in the LaTeX output directory (e.g., sphinx/latex), not sphinx/html; update these paths to match the actual build output directories.

Suggested change

	To generate a pdf for the Sphinx docs, navigate to `sphinx/html` and run `make` in
	To generate a pdf for the Sphinx docs, navigate to `sphinx/latex` and run `make` in

[Copilot]

The paths here don’t match the repo layout: the API docs live under docs/api/ (lowercase), and the TOC file is under docs/sphinx/_toc.yml.in. As written, contributors may add content in the wrong place or update the wrong TOC file.

Suggested change

	belongs in `docs/API` and other documentation goes in `docs`. Be sure to update
	`sphinx/_toc.yml.in` if you add any new files.
	belongs in `docs/api/` and other documentation goes in `docs/`. Be sure to update
	`docs/sphinx/_toc.yml.in` if you add any new files.

[Copilot]

conf.py raises a RuntimeError unless DOXYGEN_ROOT and DOXYGEN_XML_DIR are set. With the current .readthedocs.yaml (which just runs Sphinx), Read the Docs builds will fail unless you also add RTD build steps to generate Doxygen output and export these env vars (or make conf.py handle RTD builds differently).

Suggested change

	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)
	on_rtd = os.environ.get("READTHEDOCS") == "True"
	if (not doxygen_root or not doxygen_xml_dir) and not on_rtd:
	raise RuntimeError(
	"DOXYGEN_ROOT and DOXYGEN_XML_DIR must be set. "
	"Build this documentation via CMake, not directly with sphinx-build."
	)
	if doxygen_root and doxygen_xml_dir:
	docs_core.run_doxygen(doxygen_root=doxygen_root, doxygen_path=doxygen_xml_dir)

[ammallya]

Imported to ROCm/rocm-systems pull 4863