Skip to content

Add pybind11 docs #2657

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kwokcb wants to merge 16 commits into
base: main
Choose a base branch
from
+564 −6
Open

Add pybind11 docs #2657

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
4d19085
Doxygen docs insertion into pybind cpp code.
kwokcb Nov 4, 2025
0c3dc85
Simplify and add in "force" replacement of docs.
kwokcb Nov 4, 2025
0725131
Merge branch 'AcademySoftwareFoundation:main' into pybind11_docs
kwokcb Nov 7, 2025
8dc0f8e
Merge branch 'AcademySoftwareFoundation:main' into pybind11_docs
kwokcb Nov 10, 2025
9c02fd7
Merge branch 'AcademySoftwareFoundation:main' into pybind11_docs
kwokcb Nov 11, 2025
16a61d1
Merge branch 'AcademySoftwareFoundation:main' into pybind11_docs
kwokcb Nov 12, 2025
7597e31
Merge branch 'AcademySoftwareFoundation:main' into pybind11_docs
kwokcb Nov 17, 2025
57b928a
Automate docs insertion for PyMaterialX by adding in a docs dependency.
kwokcb Nov 17, 2025
0ff87e1
Fix docs build logic in main.yml.
kwokcb Nov 17, 2025
54c9a5a
Make wheels build (re)generate docs.
kwokcb Nov 17, 2025
1fce313
Needs documents while building. Exclude from the wheel.
kwokcb Nov 17, 2025
1b75c91
Cleanup logic
kwokcb Nov 18, 2025
fabfe2a
Remove non-ansi characters.
kwokcb Nov 18, 2025
8c0f30b
Merge branch 'AcademySoftwareFoundation:main' into pybind11_docs
kwokcb Nov 24, 2025
16560b1
Merge remote-tracking branch 'upstream/main' into pybind11_docs
kwokcb Dec 10, 2025
d4ac99b
Revert so source does not have embedded pybind docs.
kwokcb Dec 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .github/workflows/main.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -458,7 +458,9 @@ jobs:
CIBW_SKIP: '*musllinux*'
CIBW_ARCHS: 'auto64'
CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
CIBW_BEFORE_ALL_LINUX: yum install -y libXt-devel
CIBW_BEFORE_ALL_LINUX: yum install -y libXt-devel doxygen
CIBW_BEFORE_ALL_MACOS: brew install doxygen
CIBW_BEFORE_ALL_WINDOWS: choco install doxygen.install -y
CIBW_BUILD_VERBOSITY: 1
CIBW_ENVIRONMENT: CMAKE_BUILD_PARALLEL_LEVEL=2
MACOSX_DEPLOYMENT_TARGET: '11.0'
Expand Down
10 changes: 6 additions & 4 deletions CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,7 @@ set(MATERIALX_PYTHON_EXECUTABLE "" CACHE FILEPATH
"Python executable to be used in building the MaterialX Python package (e.g. 'C:/Python39/python.exe').")
set(MATERIALX_PYTHON_PYBIND11_DIR "" CACHE PATH
"Path to a folder containing the PyBind11 source to be used in building MaterialX Python.")
option(MATERIALX_PYTHON_FORCE_REPLACE_DOCS "Force replace existing docstrings when generating Python binding documentation from Doxygen." OFF)
Copy link
Contributor Author

@kwokcb kwokcb Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Option to allow replacement of docs at build level. Used for wheels and can be used in local or CI builds.


# Settings to define installation layout
set(MATERIALX_INSTALL_INCLUDE_PATH "include" CACHE STRING "Install header include path (e.g. 'inc', 'include').")
Expand Down Expand Up @@ -197,6 +198,7 @@ mark_as_advanced(MATERIALX_DYNAMIC_ANALYSIS)
mark_as_advanced(MATERIALX_PYTHON_VERSION)
mark_as_advanced(MATERIALX_PYTHON_EXECUTABLE)
mark_as_advanced(MATERIALX_PYTHON_PYBIND11_DIR)
mark_as_advanced(MATERIALX_PYTHON_FORCE_REPLACE_DOCS)
mark_as_advanced(MATERIALX_OSL_BINARY_OSLC)
mark_as_advanced(MATERIALX_OSL_BINARY_TESTRENDER)
mark_as_advanced(MATERIALX_OSL_INCLUDE_PATH)
Expand Down Expand Up @@ -535,16 +537,16 @@ if(MATERIALX_BUILD_TESTS)
add_subdirectory(source/MaterialXTest)
endif()

if (MATERIALX_BUILD_DOCS)
add_subdirectory(documents)
endif()

# Add Python subdirectories
if(MATERIALX_BUILD_PYTHON)
add_subdirectory(source/PyMaterialX)
add_subdirectory(python)
endif()

if(MATERIALX_BUILD_DOCS)
add_subdirectory(documents)
endif()

if(MATERIALX_BUILD_JS)
add_subdirectory(source/JsMaterialX)
endif()
Expand Down
3 changes: 3 additions & 0 deletions documents/Doxyfile.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,6 @@ FULL_SIDEBAR = NO

QUIET = YES
WARN_IF_UNDOCUMENTED = NO

GENERATE_XML = YES
Copy link
Contributor Author

@kwokcb kwokcb Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This runs very fast and will allow anyone to parse the XML docs as desired.

XML_OUTPUT = doxygen_xml
12 changes: 11 additions & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,17 +56,25 @@ logging.level = "DEBUG"
# where the package is.
wheel.packages = ["python/MaterialX"]

sdist.include = [
"/documents",
]

sdist.exclude = [
"/build",
"/dist",
"/resources",
"/javascript",
"/documents",
"/.github",
"MANIFEST.in",
"/source/JsMaterialX",
]

wheel.exclude = [
Copy link
Contributor Author

@kwokcb kwokcb Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't want the html docs files for now in the package. If / when html docs are build for Python they can be included.

"/documents",
"documents/",
]

[tool.scikit-build.metadata.version]
# https://scikit-build-core.readthedocs.io/en/latest/configuration.html#dynamic-metadata
provider = "scikit_build_core.metadata.regex"
Expand All @@ -81,6 +89,8 @@ result = "{major}.{minor}.{build}"
[tool.scikit-build.cmake.define]
MATERIALX_BUILD_SHARED_LIBS = 'OFF' # Be explicit
MATERIALX_BUILD_PYTHON = 'ON'
MATERIALX_BUILD_DOCS = 'ON'
Copy link
Contributor Author

@kwokcb kwokcb Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto build docs. Replaces all existing docs.

MATERIALX_PYTHON_FORCE_REPLACE_DOCS = 'ON'
MATERIALX_TEST_RENDER = 'OFF'
MATERIALX_WARNINGS_AS_ERRORS = 'ON'
MATERIALX_BUILD_TESTS = 'OFF'
Expand Down
Loading