Add Python documentation generation

.github/workflows/docs.yml

@@ -1,4 +1,5 @@
 name: docs
+description: Build and deploy documentation (both C++/slang and Python/pyslang)
 
 on:
   push:
@@ -14,16 +15,22 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0
+    - name: Install Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
     - name: Install dependencies
       run: |
-        pip install jinja2 pygments
+        pip install jinja2 pygments docutils
         wget https://sourceforge.net/projects/doxygen/files/rel-1.13.2/doxygen-1.13.2.linux.bin.tar.gz
         tar -xvf doxygen-1.13.2.linux.bin.tar.gz
         cp doxygen-1.13.2/bin/doxygen /usr/local/bin
-    - name: Build
+    - name: Build slang and pyslang docs via CMake
       run: |
         cmake -B build -DSLANG_INCLUDE_DOCS=ON -DSLANG_INCLUDE_TESTS=OFF
         cmake --build build --target docs -j8
+    - name: Compress docs artifacts
+      run: |
         tar -czvf slang.tar.gz build/docs build/bin/slang
     - name: Upload
       if: github.event_name != 'pull_request'

bindings/python/StatementBindings.cpp

@@ -27,7 +27,7 @@ void registerStatements(py::module_& m) {
             return fmt::format("Statement(StatementKind.{})", toString(self.kind));
         });
 
-    py::enum_<Statement::EvalResult>(stmt, "EvalResult")
+    py::enum_<Statement::EvalResult>(m, "EvalResult")
         .value("Fail", Statement::EvalResult::Fail)
         .value("Success", Statement::EvalResult::Success)
         .value("Return", Statement::EvalResult::Return)

docs/CMakeLists.txt

@@ -5,8 +5,9 @@
 
 FetchContent_Declare(
   mcss
-  URL https://github.com/MikePopoloski/m.css/releases/download/release-6/mcss.zip
-  URL_HASH MD5=df18825299064642a6f1b5df44faf80c
+  URL https://github.com/parker-research/m.css/archive/refs/heads/mike-re-add-python.zip # FIXME:
+                                                                                         # Update.
+  URL_HASH MD5=2380ae79a15bf624d8667b50ef6c936b
   SOURCE_DIR "${PROJECT_BINARY_DIR}/mcss"
   UPDATE_DISCONNECTED YES)
 FetchContent_MakeAvailable(mcss)
@@ -37,7 +38,8 @@ set(DOXYGEN_TAGFILES
 set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
 set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
 set(SCRIPTS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../scripts)
-set(DOXYGENPY_PATH "${mcss_SOURCE_DIR}/documentation/doxygen.py")
+set(MCSS_DOXYGENPY_PATH "${mcss_SOURCE_DIR}/documentation/doxygen.py")
+set(MCSS_PYTHONPY_PATH "${mcss_SOURCE_DIR}/documentation/python.py")
 
 string(REPLACE ";" " " DOXYGEN_INPUT_DIR "${DOXYGEN_INPUT_DIR_LIST}")
 string(REPLACE ";" " " DOXYGEN_EXAMPLE_DIRS "${DOXYGEN_EXAMPLE_DIR_LIST}")
@@ -60,10 +62,33 @@ add_custom_command(
           ${CMAKE_CURRENT_BINARY_DIR}/warnings.dox
   COMMAND "${CMAKE_COMMAND}" -E rm -rf ${CMAKE_CURRENT_BINARY_DIR}/html
           ${CMAKE_CURRENT_BINARY_DIR}/xml
-  COMMAND ${Python_EXECUTABLE} ${DOXYGENPY_PATH} ${DOXYFILE_OUT}
+  COMMAND ${Python_EXECUTABLE} ${MCSS_DOXYGENPY_PATH} ${DOXYFILE_OUT}
   MAIN_DEPENDENCY ${DOXYFILE_OUT}
   ${DOXYFILE_IN}
   COMMENT "Generating docs"
   VERBATIM)
 
 add_custom_target(docs ALL DEPENDS ${DOXYGEN_INDEX_FILE})
+
+# --- Python documentation with virtual environment ---
+set(PYTHON_DOCS_DIR ${CMAKE_CURRENT_BINARY_DIR}/pyslang)
+set(PYTHON_VENV_DIR ${PROJECT_BINARY_DIR}/venv)
+file(MAKE_DIRECTORY ${PYTHON_DOCS_DIR})
+
+add_custom_command(
+  OUTPUT ${PYTHON_DOCS_DIR}/index.html
+  COMMAND ${Python_EXECUTABLE} -m venv ${PYTHON_VENV_DIR}
+  COMMAND ${PYTHON_VENV_DIR}/bin/python -m pip install --upgrade pip
+  COMMAND ${PYTHON_VENV_DIR}/bin/python -m pip install jinja2 pygments docutils
+  COMMAND ${PYTHON_VENV_DIR}/bin/python -m pip install .
+  COMMAND ${PYTHON_VENV_DIR}/bin/python ${MCSS_PYTHONPY_PATH}
+          ${PROJECT_SOURCE_DIR}/pyslang/docs/conf.py
+  WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+  DEPENDS ${PROJECT_SOURCE_DIR}/pyslang/docs/conf.py
+  COMMENT "Generating Python docs in virtual environment"
+  VERBATIM)
+
+add_custom_target(python_docs DEPENDS ${PYTHON_DOCS_DIR}/index.html)
+
+# Make sure both docs and python_docs are built with `make docs`
+add_dependencies(docs python_docs)

docs/Doxyfile.in

@@ -1,5 +1,9 @@
 # Doxyfile 1.13.2
 
+# Note that this file cloned-and-modified by the settings in CMakeLists.txt.
+# Various placeholders (e.g., `@DOXYGEN_OUTPUT_DIR@`) are replaced with the
+# values of the corresponding CMake variables.
+
 # This file describes the settings to be used by the documentation system
 # Doxygen (www.doxygen.org) for a project.
 #

pyslang/docs/conf.py

@@ -0,0 +1,22 @@
+# Docs: https://mcss.mosra.cz/documentation/python/
+# Run this file with `<mcss_clone_path>/documentation/python.py <path_to_this_file>`
+
+from pathlib import Path
+
+# Find the root of the git repository.
+_GIT_REPO_ROOT_PATH = Path(__file__).parent.parent.parent
+assert (
+    _GIT_REPO_ROOT_PATH / ".git"
+).is_dir(), "Git repository root not found/set incorrectly"
+
+_DOCS_OUTPUT_PATH = _GIT_REPO_ROOT_PATH / "build/docs/html/pyslang"
+_DOCS_OUTPUT_PATH.mkdir(parents=True, exist_ok=True)
+
+# Set the m.css configuration variables.
+PROJECT_TITLE = "pyslang"
+INPUT_MODULES = ["pyslang"]
+PYBIND11_COMPATIBILITY = True
+OUTPUT = str(_DOCS_OUTPUT_PATH.absolute())
+
+# Output the stubs for comparison/review, but not actually used.
+OUTPUT_STUBS = str((_GIT_REPO_ROOT_PATH / "build/stubs").absolute())