[docs] add Read the Docs C++ API reference (#354)

## Summary
- Problem: issue #88 asks for the C++ API surface to be available on
Read the Docs, but the docs currently only expose narrative guides.
- Scope: add a Doxygen+Breathe docs pipeline for curated `envpool/core`
headers, wire the new page into the existing Sphinx/RTD nav, and bump
the package version for a docs-only patch release.
- Outcome: RTD builds a browsable C++ API reference page alongside the
existing `new_env` guide, without changing runtime behavior.

This diff adds a generated C++ API reference to RTD and keeps the
release semantics at a patch bump because the change is
documentation-only.

## Technical Details
- Approach: generate Doxygen XML during the Sphinx build, point Breathe
at that XML, and render a curated set of core classes/types instead of
dumping the entire header tree.
- Code pointers:
- `docs/conf.py`: configures the Doxygen XML generation hook and Breathe
project mapping.
- `docs/content/cpp_interface.rst`: defines the new curated C++ API
reference page.
- `.readthedocs.yaml`: installs `doxygen` in RTD so the docs build is
self-contained.
- `envpool/__init__.py`: bumps the package version to `0.9.1` for this
docs-only release.
- Notes: the docs link back into `content/new_env.rst`, and the version
bump is intentionally `patch` because there is no API or behavior
change.

## Test Plan
### Automated
- `python3 -m compileall docs/conf.py`: passed locally.
- `brix ssh dev -C -- 'bash /tmp/envpool_issue88_devbox.sh'`: passed on
`dev`; installs docs deps, runs `make -C docs html`, and verifies
`docs/_build/html/content/cpp_interface.html` contains the generated C++
API page.
### Suggested Manual
- `make -C docs html`: verify the new `C++ API Reference` page appears
in the Content nav.
- Open `docs/_build/html/content/cpp_interface.html`: spot-check key
entries like `AsyncEnvPool`, `EnvSpec`, and `PyEnvPool`.

Closes #88.

Author: Trinkle23897

.readthedocs.yaml

@@ -8,6 +8,8 @@ version: 2
 # Set the version of Python and other tools you might need
 build:
   os: ubuntu-22.04
+  apt_packages:
+    - doxygen
   tools:
     python: "3.12"
 

Makefile

@@ -45,6 +45,9 @@ clang-tidy-install:
 	mkdir -p $(CLANG_TIDY_WRAPPER_DIR)
 	ln -sf $$(command -v $(CLANG_TIDY_BIN)) $(CLANG_TIDY_WRAPPER_DIR)/clang-tidy
 
+doxygen-install:
+	command -v doxygen || (if command -v sudo >/dev/null 2>&1; then sudo apt-get update && sudo apt-get install -y doxygen; else apt-get update && apt-get install -y doxygen; fi)
+
 go-install:
 	# requires go >= 1.16
 	command -v go || (sudo apt-get install -y golang-1.18 && sudo ln -sf /usr/lib/go-1.18/bin/go /usr/bin/go)
@@ -58,12 +61,13 @@ buildifier-install: go-install
 addlicense-install: go-install
 	command -v addlicense || go install github.com/google/addlicense@latest
 
-doc-install:
+doc-install: doxygen-install
 	$(call check_install_extra, doc8, "doc8<1")
 	$(call check_install, setuptools)
 	$(call check_install, pbr)
 	$(call check_install, sphinx)
 	$(call check_install, sphinx_rtd_theme)
+	$(call check_install, breathe)
 
 spelling-install: doc-install spelling-system-install
 	$(call check_install_extra, sphinxcontrib.spelling, sphinxcontrib.spelling pyenchant)

docs/conf.py

@@ -17,6 +17,23 @@
 # sys.path.insert(0, os.path.abspath('.'))
 
 import os
+import shutil
+import subprocess
+
+CPP_API_HEADERS = [
+    "envpool/core/array.h",
+    "envpool/core/spec.h",
+    "envpool/core/dict.h",
+    "envpool/core/env_spec.h",
+    "envpool/core/env.h",
+    "envpool/core/envpool.h",
+    "envpool/core/async_envpool.h",
+    "envpool/core/py_envpool.h",
+]
+DOCS_DIR = os.path.abspath(os.path.dirname(__file__))
+PROJECT_ROOT = os.path.abspath(os.path.join(DOCS_DIR, ".."))
+DOXYGEN_BUILD_DIR = os.path.join(DOCS_DIR, "_build", "doxygen")
+DOXYGEN_XML_DIR = os.path.join(DOXYGEN_BUILD_DIR, "xml")
 
 
 def get_version() -> str:
@@ -42,6 +59,7 @@ def get_version() -> str:
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "breathe",
     "sphinx.ext.autodoc",
 ]
 
@@ -57,6 +75,9 @@ def get_version() -> str:
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 spelling_exclude_patterns = ["pages/slides.rst"]
+breathe_projects = {"envpool_cpp_api": DOXYGEN_XML_DIR}
+breathe_domain_by_extension = {"h": "cpp"}
+breathe_default_members = ("members", "undoc-members")
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -73,8 +94,41 @@ def get_version() -> str:
 html_logo = "_static/images/envpool-logo.png"
 
 
+def generate_doxygen_xml(_app):
+    """Generate the Doxygen XML consumed by Breathe."""
+    doxygen = shutil.which("doxygen")
+    if doxygen is None:
+        raise RuntimeError("doxygen is required to build the C++ API docs")
+    os.makedirs(DOXYGEN_BUILD_DIR, exist_ok=True)
+    doxyfile = os.path.join(DOXYGEN_BUILD_DIR, "Doxyfile")
+    inputs = " \\\n".join(
+        os.path.join(PROJECT_ROOT, header) for header in CPP_API_HEADERS
+    )
+    with open(doxyfile, "w", encoding="utf-8") as f:
+        f.write(
+            f"""PROJECT_NAME = "EnvPool C++ API"
+OUTPUT_DIRECTORY = "{DOXYGEN_BUILD_DIR}"
+INPUT = {inputs}
+FILE_PATTERNS = *.h
+RECURSIVE = NO
+GENERATE_HTML = NO
+GENERATE_LATEX = NO
+GENERATE_XML = YES
+XML_OUTPUT = xml
+EXTRACT_ALL = YES
+EXTRACT_PRIVATE = NO
+EXTRACT_STATIC = YES
+QUIET = YES
+WARN_IF_UNDOCUMENTED = NO
+STRIP_FROM_PATH = "{PROJECT_ROOT}"
+"""
+        )
+    subprocess.run([doxygen, doxyfile], check=True, cwd=PROJECT_ROOT)
+
+
 def setup(app):
     """Register the Sphinx configuration hooks."""
+    app.connect("builder-inited", generate_doxygen_xml)
     app.add_js_file("js/copybutton.js")
     app.add_css_file("css/style.css")
 

docs/content/cpp_interface.rst

@@ -0,0 +1,64 @@
+C++ API Reference
+=================
+
+This reference is generated from the curated ``envpool/core`` headers used by
+the :doc:`new_env` integration guide. It is meant to make the C++ extension
+surface available on Read the Docs alongside the narrative guide.
+
+
+Core Data Structures
+--------------------
+
+.. doxygenclass:: Array
+   :project: envpool_cpp_api
+
+.. doxygenclass:: TArray
+   :project: envpool_cpp_api
+
+.. doxygenclass:: ShapeSpec
+   :project: envpool_cpp_api
+
+.. doxygenclass:: Spec
+   :project: envpool_cpp_api
+
+The compile-time dictionary helpers used by these types still live in
+``envpool/core/dict.h`` and are referenced throughout :doc:`new_env`.
+
+
+Environment Authoring
+---------------------
+
+.. doxygenvariable:: common_config
+   :project: envpool_cpp_api
+
+.. doxygenvariable:: common_action_spec
+   :project: envpool_cpp_api
+
+.. doxygenvariable:: common_state_spec
+   :project: envpool_cpp_api
+
+.. doxygenclass:: EnvSpec
+   :project: envpool_cpp_api
+
+.. doxygenclass:: Env
+   :project: envpool_cpp_api
+
+
+Pool Implementations
+--------------------
+
+.. doxygenclass:: EnvPool
+   :project: envpool_cpp_api
+
+.. doxygenclass:: AsyncEnvPool
+   :project: envpool_cpp_api
+
+
+Python Binding Helpers
+----------------------
+
+.. doxygenclass:: PyEnvSpec
+   :project: envpool_cpp_api
+
+.. doxygenclass:: PyEnvPool
+   :project: envpool_cpp_api

docs/content/new_env.rst

@@ -4,6 +4,8 @@ Add New Environment into EnvPool
 To add a new environment in C++ that EnvPool will parallelly run, we provide a
 developer interface in `envpool/core/env.h
 <https://github.com/sail-sg/envpool/blob/main/envpool/core/env.h>`_.
+The generated reference for the core headers used below is available in
+:doc:`cpp_interface`.
 
 - For a quick and annotated example, please refer to
   `envpool/dummy/ <https://github.com/sail-sg/envpool/tree/main/envpool/dummy>`_.

docs/index.rst

@@ -76,6 +76,7 @@ stable version through `envpool.readthedocs.io/en/stable/
    content/slides
    content/build
    content/python_interface
+   content/cpp_interface
    content/xla_interface
    content/benchmark
    content/new_env

docs/requirements.txt

@@ -1,2 +1,3 @@
+breathe
 sphinx
 sphinx_rtd_theme

docs/spelling_wordlist.txt

@@ -72,3 +72,5 @@ jit
 mins
 lidar
 procgen
+Subclassed
+deleter

envpool/__init__.py

@@ -30,7 +30,7 @@
 if not hasattr(np, "bool8"):
     np.__dict__["bool8"] = np.bool_
 
-__version__ = "0.9.0"
+__version__ = "0.9.1"
 __all__ = [
     "register",
     "make",

envpool/core/env_spec.h

@@ -43,7 +43,7 @@ auto common_state_spec =
              "step_type"_.Bind(Spec<int>({})), "trunc"_.Bind(Spec<bool>({})));
 
 /**
- * EnvSpec funciton, it constructs the env spec when a Config is passed.
+ * EnvSpec function, it constructs the env spec when a Config is passed.
  */
 template <typename EnvFns>
 class EnvSpec {