Update config to build and deploy documentation.

- Add Doxygen config to build API documentation;
- Add Sphinx config to build high-level documentation and installation guides;
- Move content of Doxygen groups into Sphinx pages;
- Add sphinxcontrib-doxylink to reference API doc symbols from Sphinx;
- Add Github CI job to deploy documentation on Github Page;
- Fix bug in vsnprintf.h to document ArchVStringPrintf.

.github/workflows/docs-deploy.yml

@@ -0,0 +1,59 @@
+name: docs-deploy
+
+on:
+  push:
+    branches: [ main ]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Create Build Environment
+        working-directory: ${{runner.temp}}
+        run: |
+          brew install doxygen
+          python -m pip install --upgrade pip
+          python -m pip install -r ${{github.workspace}}/doc/requirements.txt
+          npm install https://github.com/jothepro/doxygen-awesome-css#v2.3.3
+          cmake -E make_directory ${{github.workspace}}/build
+
+      - name: Build documentation
+        working-directory: ${{github.workspace}}/build
+        run: |
+          cmake \
+            -D "BUILD_TESTS=OFF" \
+            -D "DOXYGEN_HTML_EXTRA_STYLESHEET=${{runner.temp}}/node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome.css" ..
+          cmake --build . --target documentation
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ${{github.workspace}}/build/doc/doc/pxr/arch
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: macos-latest
+    needs: build
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/linux.yml

@@ -31,7 +31,7 @@ jobs:
 
       - name: Configure
         working-directory: ${{github.workspace}}/build
-        run: cmake ..
+        run: cmake -D "BUILD_DOCS=OFF" ..
 
       - name: Build
         working-directory: ${{github.workspace}}/build

.github/workflows/macos.yml

@@ -30,7 +30,7 @@ jobs:
 
       - name: Configure
         working-directory: ${{github.workspace}}/build
-        run: cmake ..
+        run: cmake -D "BUILD_DOCS=OFF" ..
 
       - name: Build
         working-directory: ${{github.workspace}}/build

.github/workflows/windows.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Configure
         working-directory: ${{github.workspace}}/build
-        run: cmake -D "ENABLE_PRECOMPILED_HEADERS=ON" ..
+        run: cmake -D "BUILD_DOCS=OFF" -D "ENABLE_PRECOMPILED_HEADERS=ON" ..
 
       - name: Build
         working-directory: ${{github.workspace}}/build

CMakeLists.txt

@@ -19,6 +19,7 @@ set(CMAKE_CXX_EXTENSIONS OFF)
 
 # Default options.
 option(BUILD_TESTS "Build tests" ON)
+option(BUILD_DOCS "Build documentation" ON)
 option(BUILD_SHARED_LIBS "Build Shared Library" ON)
 option(ENABLE_PRECOMPILED_HEADERS "Enable precompiled headers." OFF)
 
@@ -58,6 +59,14 @@ if (BUILD_TESTS)
     add_subdirectory(test)
 endif()
 
+# Build documentation if required.
+if (BUILD_DOCS)
+    find_package(Sphinx 1.8.6 REQUIRED)
+    find_package(Doxygen 1.8.5 REQUIRED)
+
+    add_subdirectory(doc)
+endif()
+
 include(CMakePackageConfigHelpers)
 
 configure_package_config_file(

README.md

@@ -17,3 +17,8 @@ It is regularly rebased over the "release" branch of the original
 explicit divergence information from the latest updates and is currently
 synchronized with
 [v25.02](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v25.02).
+
+## Documentation
+
+Full documentation, including installation and setup guides, can be found at
+https://untwine.github.io/pxr-arch/

doc/CMakeLists.txt

@@ -0,0 +1,55 @@
+file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/doc/pxr/arch")
+
+set(DOXYGEN_PROJECT_NAME "Pixar Arch")
+set(DOXYGEN_PROJECT_ICON "${PROJECT_SOURCE_DIR}/doc/sphinx/favicon.ico")
+set(DOXYGEN_HTML_OUTPUT "doc/pxr/arch/doxygen")
+set(DOXYGEN_EXTENSION_MAPPING "h=C++")
+set(DOXYGEN_GENERATE_HTML YES)
+set(DOXYGEN_GENERATE_LATEX NO)
+set(DOXYGEN_GENERATE_TREEVIEW YES)
+set(DOXYGEN_QUIET YES)
+set(DOXYGEN_SORT_MEMBER_DOCS NO)
+set(DOXYGEN_FULL_PATH_NAMES NO)
+set(DOXYGEN_FILE_PATTERNS *.dox *.h)
+set(DOXYGEN_ALWAYS_DETAILED_SEC YES)
+set(DOXYGEN_JAVADOC_AUTOBRIEF YES)
+set(DOXYGEN_BUILTIN_STL_SUPPORT YES)
+set(DOXYGEN_INLINE_SIMPLE_STRUCTS YES)
+set(DOXYGEN_PREDEFINED doxygen)
+set(DOXYGEN_QUIET YES)
+set(DOXYGEN_EXTRACT_ALL YES)
+set(DOXYGEN_WARN_IF_DOC_ERROR NO)
+set(DOXYGEN_EXCLUDE
+    "${PROJECT_SOURCE_DIR}/src/pxr/arch/api.h"
+    "${PROJECT_SOURCE_DIR}/src/pxr/arch/pch.h"
+)
+set(DOXYGEN_GENERATE_TAGFILE
+    "${CMAKE_CURRENT_BINARY_DIR}/doc/pxr/arch/pxr-arch.tag")
+
+doxygen_add_docs(archApiRefDoc
+    "${PROJECT_SOURCE_DIR}/doc/doxygen/index.dox"
+    "${PROJECT_SOURCE_DIR}/doc/doxygen/namespaces.dox"
+    "${PROJECT_SOURCE_DIR}/src/pxr/arch"
+)
+
+file(COPY sphinx DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
+configure_file(sphinx/conf.py sphinx/conf.py @ONLY)
+
+sphinx_add_docs(archDoc
+    SOURCE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/sphinx"
+    OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/doc/pxr/arch"
+    DEPENDS archApiRefDoc
+)
+
+add_custom_target(documentation ALL)
+add_dependencies(documentation
+    archDoc
+    archApiRefDoc
+)
+
+install(
+    DIRECTORY
+        "${CMAKE_CURRENT_BINARY_DIR}/doc"
+    DESTINATION
+        ${CMAKE_INSTALL_PREFIX}
+)

doc/doxygen/index.dox

@@ -0,0 +1,11 @@
+/*!
+\mainpage Home
+
+Abstract architecture-dependent logic.
+
+Read the [documentation](../index.html), or explore [the API](\ref pxr).
+
+<HR>
+
+Copyright 2024, Pixar, modified by Jeremy Retailleau
+*/

doc/doxygen/namespaces.dox

@@ -0,0 +1,4 @@
+/*!
+\namespace pxr
+Scope of the Pixar libraries.
+*/

doc/requirements.txt

@@ -0,0 +1,4 @@
+Sphinx==7.4.7
+sphinx-cmake==0.2.1
+sphinx-rtd-theme==2.0.0
+sphinxcontrib-doxylink==1.12.3

doc/sphinx/_templates/breadcrumbs.html

@@ -0,0 +1,4 @@
+{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
+
+{% block breadcrumbs_aside %}
+{% endblock %}

doc/sphinx/api_reference/index.rst

@@ -0,0 +1,7 @@
+.. _api_reference:
+
+*************
+API Reference
+*************
+
+* `C++ API Documentation <../doxygen/index.html>`_

doc/sphinx/bits.rst

@@ -0,0 +1,14 @@
+.. _bits:
+
+****
+Bits
+****
+
+Functions having to do with how bits are laid out on a machine.
+
+.. _bits/files:
+
+Files
+~~~~~
+
+* :arch-cpp:`inttypes.h`

doc/sphinx/conf.py

@@ -0,0 +1,23 @@
+"""Arch documentation build configuration file."""
+
+import pathlib
+
+# -- General ------------------------------------------------------------------
+
+extensions = ["sphinxcontrib.doxylink"]
+templates_path = ["_templates"]
+source_suffix = ".rst"
+master_doc = "index"
+
+project = "Pixar Arch"
+copyright = "2024, Pixar, modified by Jeremy Retailleau"
+
+build_path = pathlib.Path("@CMAKE_CURRENT_BINARY_DIR@/doc/pxr/arch")
+doxylink = {"arch-cpp": ((build_path / "pxr-arch.tag").as_posix(), "./doxygen")}
+add_function_parentheses = True
+
+# -- HTML output --------------------------------------------------------------
+
+html_theme = "sphinx_rtd_theme"
+html_favicon = "favicon.ico"
+html_show_sphinx = False

doc/sphinx/diagnostics.rst

@@ -0,0 +1,70 @@
+.. _diagnostics:
+
+***********
+Diagnostics
+***********
+
+Functions having to do with error reporting/handling.
+
+.. _diagnostics/files:
+
+Files
+~~~~~
+
+* :arch-cpp:`error.h`
+* :arch-cpp:`stackTrace.h`
+* :arch-cpp:`symbols.h`
+
+.. _diagnostics/macros:
+
+Macros
+~~~~~~
+
+* :arch-cpp:`ARCH_ERROR`
+* :arch-cpp:`ARCH_WARNING`
+* :arch-cpp:`ARCH_AXIOM`
+
+.. _diagnostics/typedefs:
+
+Typedefs
+~~~~~~~~
+
+* :arch-cpp:`ArchStackTraceCallback`
+* :arch-cpp:`ArchCrashHandlerSystemCB`
+
+.. _diagnostics/functions:
+
+Functions
+~~~~~~~~~
+
+* :arch-cpp:`ArchLogFatalProcessState`
+* :arch-cpp:`ArchLogCurrentProcessState`
+* :arch-cpp:`ArchSetProcessStateLogCommand`
+* :arch-cpp:`ArchIsAppCrashing`
+* :arch-cpp:`ArchLogSessionInfo`
+* :arch-cpp:`ArchSetLogSession`
+* :arch-cpp:`ArchEnableSessionLogging`
+* :arch-cpp:`ArchPrintStackTrace(FILE*, const std::string&, const std::string&)`
+* :arch-cpp:`ArchPrintStackTrace(FILE*, const std::string&)`
+* :arch-cpp:`ArchPrintStackTrace(std::ostream&, const std::string&, const std::string&)`
+* :arch-cpp:`ArchPrintStackTrace(std::ostream&, const std::string&)`
+* :arch-cpp:`ArchSetStackTraceCallback`
+* :arch-cpp:`ArchGetStackTraceCallback`
+* :arch-cpp:`ArchGetAppLaunchTime`
+* :arch-cpp:`ArchSetFatalStackLogging`
+* :arch-cpp:`ArchGetFatalStackLogging`
+* :arch-cpp:`ArchSetProgramNameForErrors`
+* :arch-cpp:`ArchGetProgramNameForErrors`
+* :arch-cpp:`ArchSetProgramInfoForErrors`
+* :arch-cpp:`ArchGetProgramInfoForErrors`
+* :arch-cpp:`ArchSetExtraLogInfoForErrors`
+* :arch-cpp:`ArchLogStackTrace(const std::string&, const std::string&, bool = false, const std::string& = "")`
+* :arch-cpp:`ArchLogStackTrace(const std::string&, bool = false, const std::string& = "")`
+* :arch-cpp:`ArchGetStackTrace`
+* :arch-cpp:`ArchGetStackFrames(size_t, std::vector< uintptr_t >*)`
+* :arch-cpp:`ArchGetStackFrames(size_t, uintptr_t*)`
+* :arch-cpp:`ArchGetStackFrames(size_t, size_t, std::vector< uintptr_t >*)`
+* :arch-cpp:`ArchGetStackFrames(size_t, size_t, uintptr_t*)`
+* :arch-cpp:`ArchPrintStackFrames`
+* :arch-cpp:`ArchCrashHandlerSystemv`
+* :arch-cpp:`ArchGetAddressInfo`

doc/sphinx/glossary.rst

@@ -0,0 +1,34 @@
+********
+Glossary
+********
+
+.. glossary::
+
+    CMake
+        CMake is a compilation configuration platform that manages the build
+        process in an operating system and in a compiler-independent manner.
+
+        .. seealso:: https://cmake.org/overview/
+
+    CTest
+        CTest is an executable that comes with :term:`CMake` which handles
+        running the tests.
+
+        .. seealso:: https://cmake.org/cmake/help/latest/manual/ctest.1.html
+
+    Doxygen
+        Documentation generator and static analysis tool which supports many
+        languages, including C and C++.
+
+        .. seealso:: https://doxygen.nl/
+
+    reStructuredText
+        Lightweight markup language.
+
+        .. seealso:: https://docutils.sourceforge.io/rst.html
+
+    Sphinx
+        Python documentation generator which converts :term:`reStructuredText`
+        files into HTML and other formats.
+
+        .. seealso:: https://www.sphinx-doc.org/

doc/sphinx/index.rst

@@ -0,0 +1,24 @@
+.. _main:
+
+##########
+Pixar Arch
+##########
+
+Abstract architecture-dependent logic.
+
+.. toctree::
+    :maxdepth: 1
+
+    introduction
+    installing
+    bits
+    multithreading
+    math
+    strings
+    system_functions
+    memory_management
+    diagnostics
+    symbol_visibility
+    api_reference/index
+    Source Code @ GitHub <https://github.com/untwine/pxr-arch>
+    glossary