docs: docs GHA workflow + overaul testshade, oslquery, osltoy docs

.github/workflows/docs.yml

@@ -0,0 +1,89 @@
+# Copyright Contributors to the Open Shading Language project.
+# SPDX-License-Identifier: BSD-3-Clause
+# https://github.com/AcademySoftwareFoundation/OpenShadingLanguage
+
+name: docs
+
+on:
+  push:
+    # Skip jobs when only non-doc files are changed.
+    paths-ignore:
+      - '**/ci.yml'
+      - '**/analysis.yml'
+      - '**/scorecards.yml'
+      - '**/release-notice.yml'
+      - '**/release-sign.yml'
+      - '**.properties'
+      - 'src/**.cpp'
+      - '**.cmake'
+      - '**/CMakeLists.txt'
+      - '**/run.py'
+      - 'src/build-scripts/**'
+      - './*.md'
+  pull_request:
+    paths-ignore:
+      - '**/ci.yml'
+      - '**/analysis.yml'
+      - '**/scorecards.yml'
+      - '**/release-notice.yml'
+      - '**/release-sign.yml'
+      - '**.properties'
+      - 'src/**.cpp'
+      - '**.cmake'
+      - '**/CMakeLists.txt'
+      - '**/run.py'
+      - 'src/build-scripts/**'
+      - './*.md'
+  schedule:
+    # Full nightly build
+    - cron: "0 8 * * *"
+  workflow_dispatch:
+    # This allows manual triggering of the workflow from the web
+
+permissions: read-all
+
+# Allow subsequent pushes to the same PR or REF to cancel any previous jobs.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+
+jobs:
+  docs:
+    name: "Docs / ${{matrix.desc}}"
+    if: ${{ github.event_name != 'schedule' || github.event.repository.fork == false }}
+    uses: ./.github/workflows/build-steps.yml
+    with:
+      nametag: ${{ matrix.nametag || 'unnamed!' }}
+      runner: ${{ matrix.runner || 'ubuntu-latest' }}
+      container: ${{ matrix.container }}
+      cc_compiler: ${{ matrix.cc_compiler }}
+      cxx_compiler: ${{ matrix.cxx_compiler }}
+      cxx_std: ${{ matrix.cxx_std || '17' }}
+      build_type: ${{ matrix.build_type || 'Release' }}
+      depcmds: ${{ matrix.depcmds }}
+      extra_artifacts: ${{ matrix.extra_artifacts }}
+      python_ver: ${{ matrix.python_ver }}
+      setenvs: ${{ matrix.setenvs }}
+      simd: ${{ matrix.simd }}
+      skip_build: ${{ matrix.skip_build }}
+      skip_tests: ${{ matrix.skip_tests }}
+      abi_check: ${{ matrix.abi_check }}
+      build_docs: ${{ matrix.build_docs }}
+      generator: ${{ matrix.generator }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - desc: docs
+            nametag: docs-linux
+            runner: ubuntu-latest
+            cxx_std: 17
+            python_ver: "3.11"
+            build_docs: 1
+            skip_build: 1
+            skip_tests: 1
+            setenvs: export EXTRA_DEP_PACKAGES="doxygen sphinx-doc"
+                            PIP_INSTALLS="sphinx breathe==4.34.0 sphinx-tabs furo==2022.6.21 myst-parser linkify-it-py"
+                            SKIP_SYSTEM_DEPS_INSTALL=1

src/doc/CMakeLists.txt

@@ -2,15 +2,6 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # https://github.com/AcademySoftwareFoundation/OpenShadingLanguage
 
-set (public_docs 
-                 testshade.md.html
-                 osltoy.md.html
-                 markdeep.min.js
-                 docs.css
-                 )
-
-install (FILES ${public_docs} DESTINATION ${CMAKE_INSTALL_DOCDIR} COMPONENT documentation)
-
 install ( FILES "${PROJECT_SOURCE_DIR}/LICENSE.md"
                 "${PROJECT_SOURCE_DIR}/INSTALL.md"
                 "${PROJECT_SOURCE_DIR}/CHANGES.md"
@@ -28,56 +19,3 @@ install (FILES ${osltoy_figures}
 
 
 
-# Macro to compile a shader with oslc. Syntax is:
-#   docdeep_generate (SOURCE osl_source_file
-#                 [ NAME doc_name ]
-#                 [ DOC_LIST list_to_append_doc_filename ] )
-#                 [ SRC_LIST list_to_append_src_filename ] )
-macro (docdeep_generate)
-    cmake_parse_arguments (_docdeep "" "NAME;DOC_LIST;SRC_LIST" "SOURCE" ${ARGN})
-    # ^^ syntax: prefix options one-arg-keywords multi-arg-keywords args
-    set (oslfile ${_docdeep_SOURCE})
-    set (mdfile "${_docdeep_NAME}.md.html")
-    message (VERBOSE "docdeep will make '${mdfile}'")
-    set (docdeep_program ${CMAKE_SOURCE_DIR}/src/build-scripts/docdeep.py)
-    add_custom_command (OUTPUT ${mdfile}
-        COMMAND ${Python3_EXECUTABLE} ${docdeep_program} -d ${_docdeep_NAME} -s docs.css
-                ${_docdeep_SOURCE} > "${CMAKE_CURRENT_BINARY_DIR}/${mdfile}"
-        MAIN_DEPENDENCY ${docdeep_program}
-        DEPENDS ${_docdeep_SOURCE}
-        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-        COMMENT "docdeep ${_docdeep_NAME}"
-        )
-    if (_docdeep_DOC_LIST)
-        list (APPEND ${_docdeep_DOC_LIST} "${CMAKE_CURRENT_BINARY_DIR}/${mdfile}")
-    endif ()
-    if (_docdeep_SRC_LIST)
-        list (APPEND ${_docdeep_SRC_LIST} ${_docdeep_SOURCE})
-    endif ()
-endmacro ()
-
-
-
-set (all_docdeep_docs "")
-set (all_docdeep_srcs "")
-docdeep_generate (NAME OSLQuery
-                  SOURCE ${PROJECT_SOURCE_DIR}/src/include/OSL/oslquery.h
-                         ${PROJECT_SOURCE_DIR}/src/oslinfo/oslinfo.cpp
-                  DOC_LIST all_docdeep_docs
-                  SRC_LIST all_docdeep_srcs)
-docdeep_generate (NAME docdeep
-                  SOURCE ${PROJECT_SOURCE_DIR}/src/build-scripts/docdeep.py
-                  DOC_LIST all_docdeep_docs
-                  SRC_LIST all_docdeep_srcs)
-
-add_custom_target (generated_docs ALL
-                   DEPENDS ${all_docdeep_docs} ${all_docdeep_srcs}
-                   SOURCES ${all_docdeep_srcs}
-                   )
-
-message (STATUS "All docdeep docs = ${all_docdeep_docs}")
-
-install (FILES ${all_docdeep_docs}
-        DESTINATION ${CMAKE_INSTALL_DOCDIR}
-        COMPONENT documentation
-        )

src/doc/index.rst

@@ -59,6 +59,18 @@ Open Shading Language |version| Documentation
    glossary
 
 
+.. toctree::
+   :caption: OSL Tools
+
+   testshade
+   osltoy
+
+.. toctree::
+   :caption: OSL C++ API
+
+   oslquery
+
+
 .. comment
     This is where we would put additional documentation sections
     in the future.

src/doc/oslquery.md

@@ -0,0 +1,72 @@
+---
+numbering:
+  heading_1: true
+  heading_2: true
+  heading_3: true
+---
+
+<!--
+  Copyright Contributors to the Open Shading Language project.
+  SPDX-License-Identifier: CC-BY-4.0
+-->
+
+
+(chap-oslquery)=
+# OSLQuery: Interrogating Compiled Shaders
+
+## Introduction and Tutorial
+
+`OSLQuery` is a C++ class that lets an application interrogate a compiled
+shader for information about its parameters.
+
+The shader may be an already-compiled shader file on disk (a `.oso` file),
+or the `.oso` equivalent in a string buffer, or the binary representation
+used by the OSL `ShaderSystem` runtime (as a pointer to a `ShaderGroup`).
+For example:
+
+```cpp
+OSLQuery oslquery ("polished_oak");
+```
+
+It's then easy to retrieve a specific parameter:
+
+```cpp
+int nparams = oslquery.nparams();  // number of params
+
+const OSLQuery::Parameter *p;
+p = oslquery.getparam (i);            // by index (0..nparams-1)
+p = oslquery.getparam ("woodcolor");  // by name
+```
+
+The `Parameter` structure holds all the information you need about that
+parameter:
+
+```cpp
+std::cout << "Parameter " << p->name
+          << " is type " << p->type << "\n";
+```
+
+You can find out if the parameter is a closure, an output parameter, etc.
+Default values are stored in the vector fields `idefault`, `fdefault`, and
+`sdefault` depending on whether the type is based on `int`, `float`, or
+`string`, respectively.
+
+
+## OSLQuery API Reference
+
+```{doxygenclass} OSL::OSLQuery
+:members:
+:undoc-members:
+```
+
+
+## Example: `oslinfo`
+
+Below is the full source of `oslinfo`, a command-line utility that, for any
+compiled shader, prints its parameters (name, type, default values, and
+metadata). It serves as a complete example of using `OSLQuery`.
+
+```{literalinclude} ../oslinfo/oslinfo.cpp
+:language: cpp
+:start-at: #include <cstring>
+```