Merge pull request #1373 from Idclip/docs_to_website

Auto deploy doxygen to openvdb.org
AcademySoftwareFoundation · May 3, 2022 · 2561c25 · 2561c25
2 parents 25acbfb + 2dd12bf
commit 2561c25
Show file tree

Hide file tree

Showing 33 changed files with 89 additions and 60 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -49,17 +49,39 @@ jobs:
         ./ci/build.sh -v
         --build-type=Release
         --components="core,python,doc"
-        --cargs=\"-DUSE_BLOSC=OFF -DOPENVDB_CORE_STATIC=OFF -DOPENVDB_PYTHON_WRAP_ALL_GRID_TYPES=ON -DDISABLE_DEPENDENCY_VERSION_CHECKS=ON\"
+        --cargs=\"
+        -DUSE_BLOSC=OFF
+        -DOPENVDB_CORE_STATIC=OFF
+        -DOPENVDB_PYTHON_WRAP_ALL_GRID_TYPES=ON
+        -DUSE_EXPLICIT_INSTANTIATION=OFF
+        -DDISABLE_DEPENDENCY_VERSION_CHECKS=ON
+        \"
     - name: epydoc
       run: |
         epydoc --html -o /usr/local/share/doc/OpenVDB/html/python pyopenvdb
+    - name: pre_deploy
+      # Overwrite global SSH configuration
+      #  https://github.com/peaceiris/actions-gh-pages/issues/719
+      #  https://linuxhint.com/ssh-stricthostkeychecking/
+      run: >
+        echo "Host *
+          StrictHostKeyChecking no
+          UserKnownHostsFile=/dev/null
+        " > /etc/ssh/ssh_config
     - name: deploy
-      # only deploy documentation to gh-pages on a manual workflow dispatch
+      # only deploy documentation on a manual workflow dispatch
       if: |
         github.repository_owner == 'AcademySoftwareFoundation' &&
         github.event_name == 'workflow_dispatch' &&
         github.event.inputs.deploy == 'true'
       uses: peaceiris/actions-gh-pages@v3
       with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
+        deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
         publish_dir: /usr/local/share/doc/OpenVDB/html
+        destination_dir: documentation/doxygen
+        external_repository: AcademySoftwareFoundation/openvdb-website
+        publish_branch: doxygen
+        full_commit_message: "Automatic doxygen documentation update
+          - Deployed from: AcademySoftwareFoundation/openvdb ${{ github.sha }}
+
+          Signed-off-by: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>"
diff --git a/CHANGES b/CHANGES
@@ -422,7 +422,7 @@ Version 8.0.0 - December 23, 2020
       providing users with a new way of interacting with OpenVDB data. AX is
       tailored towards writing highly parallelizable and customizable OpenVDB
       volume and point kernel operations. See the documentation for more:
-      https://academysoftwarefoundation.github.io/openvdb/openvdbax.html
+      https://www.openvdb.org/documentation/openvdbax.html
 
     New features:
     - Added tools::anyActiveVoxels and tools::anyActiveTiles that check

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -18,12 +18,12 @@
   and required dependencies are expected. See the dependency documentation
   for more information:
 
-    https://academysoftwarefoundation.github.io/openvdb/dependencies.html
+    https://www.openvdb.org/documentation/doxygen/dependencies.html
 
   And the documentation on building OpenVDB for more in depth installation
   instructions:
 
-    https://academysoftwarefoundation.github.io/openvdb/build.html
+    https://www.openvdb.org/documentation/doxygen/build.html
 
   This CMakeLists file provides most available options for configuring the
   build and installation of all OpenVDB components. By default the core

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -10,7 +10,7 @@ The contributor role is the starting role for anyone participating in the projec
 
 ### Process for becoming a contributor
 
-* Review the [coding standards](https://academysoftwarefoundation.github.io/openvdb/codingStyle.html) to ensure your contribution is in line with the project's coding and styling guidelines.
+* Review the [coding standards](https://www.openvdb.org/documentation/doxygen/codingStyle.html) to ensure your contribution is in line with the project's coding and styling guidelines.
 * Have a signed CLA on file ( see [below](#contributor-license-agreements) )
 * Submit your code as a PR with the appropriate [DCO sign-off](#commit-sign-off).
 * Have your submission approved by the [committer(s)](#committer) and merged into the codebase.

diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@
 
 [Website](https://www.openvdb.org) |
 [Discussion Forum](https://github.com/AcademySoftwareFoundation/openvdb/discussions) |
-[Documentation](https://academysoftwarefoundation.github.io/openvdb)
+[Documentation](https://www.openvdb.org/documentation/doxygen)
 
 OpenVDB is an open source C++ library comprising a novel hierarchical data structure and a large suite of tools for the efficient storage and manipulation of sparse volumetric data discretized on three-dimensional grids. It was developed by DreamWorks Animation for use in volumetric applications typically encountered in feature film production.
 
@@ -33,7 +33,7 @@ OpenVDB welcomes contributions to the OpenVDB project. Please refer to the [cont
 
 ### Developer Quick Start
 
-The following provides basic installation examples for the core OpenVDB library. Other components, such as the python module, OpenVDB AX, NanoVDB and various executables, may require additional dependencies. See the [build documentation](https://academysoftwarefoundation.github.io/openvdb/build.html) for help with installations.
+The following provides basic installation examples for the core OpenVDB library. Other components, such as the python module, OpenVDB AX, NanoVDB and various executables, may require additional dependencies. See the [build documentation](https://www.openvdb.org/documentation/doxygen/build.html) for help with installations.
 
 #### Linux
 ##### Installing Dependencies (Boost, TBB, Blosc)
@@ -100,7 +100,7 @@ cmake --build . --parallel 4 --config Release --target install
 
 #### Building OpenVDB AX
 
-OpenVDB AX depends on the core OpenVDB library. See the [build documentation](https://academysoftwarefoundation.github.io/openvdb/build.html) for all available AX component options:
+OpenVDB AX depends on the core OpenVDB library. See the [build documentation](https://www.openvdb.org/documentation/doxygen/build.html) for all available AX component options:
 
 ```bash
 git clone [email protected]:AcademySoftwareFoundation/openvdb.git
@@ -114,7 +114,7 @@ make -j4 && make install
 #### Building NanoVDB
 
 NanoVDB can be built with and without OpenVDB support. To see full build instructions
-see the [NanoVDB build documentation](https://academysoftwarefoundation.github.io/openvdb/NanoVDB_HowToBuild.html)
+see the [NanoVDB build documentation](https://www.openvdb.org/documentation/doxygen/NanoVDB_HowToBuild.html)
 
 #### Building Without OpenVDB Support
 

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -41,6 +41,7 @@ set(DOXY_FILES
   openvdb/openvdb/io
   openvdb/openvdb/math
   openvdb/openvdb/points
+  openvdb/openvdb/points/impl
   openvdb/openvdb/python/pyopenvdb.h
   openvdb/openvdb/tools
   openvdb/openvdb/tree
@@ -215,7 +216,6 @@ if(OPENVDB_DOXYGEN_AX)
     doc/ax/doc.txt
     openvdb_ax/openvdb_ax
     openvdb_ax/openvdb_ax/ast
-    openvdb_ax/openvdb_ax/cmd
     openvdb_ax/openvdb_ax/codegen
     openvdb_ax/openvdb_ax/compiler
     openvdb_ax/openvdb_ax/grammar
@@ -235,9 +235,6 @@ if(OPENVDB_DOXYGEN_NANOVDB)
     doc/nanovdb/HelloWorld.md
     nanovdb/nanovdb
     nanovdb/nanovdb/util
-    nanovdb/nanovdb/cmd/convert
-    nanovdb/nanovdb/cmd/print
-    nanovdb/nanovdb/cmd/validate
     nanovdb/nanovdb/examples/benchmark
     nanovdb/nanovdb/examples/ex_bump_pool_buffer
     nanovdb/nanovdb/examples/ex_collide_level_set

diff --git a/doc/ax/ax.txt b/doc/ax/ax.txt
@@ -1793,7 +1793,7 @@ returned, otherwise @b `c` is evaluated and returned. In this case, @b `a` and @
 @anchor axvecmatinit
 @par Vector/Matrix Initializer
 @ref axvecmats "Vectors and matrices" can be represented as local variables (e.g.
-@b `vec3f`), external attributes or parameters (e.g. @b `vec3f@attrib`) or as
+@b `vec3f`), external attributes or parameters (e.g. @b `vec3f\@attrib`) or as
 temporary values using the vector/matrix initializer syntax. This operator has
 the form:
 @par

diff --git a/doc/ax/axexamples.txt b/doc/ax/axexamples.txt
@@ -32,7 +32,7 @@ These examples demonstrate how to use AX on OpenVDB points grids.
 Below is a small example which demonstrates working with a few point attributes.
 The @ symbol is the identifier for an AX attribute. The type of each attribute
 is specified before the @ symbol and the name is specified afterwards. For
-example: @b `int@count` would imply an @b integer attribute called @b count.
+example: @b `int\@count` would imply an @b integer attribute called @b count.
 @par
 In this example there are three point attributes: a @b float attribute @b speed,
 a @b vec3f float attribute @b velocity and a @b vec3f float attribute @b colour.
@@ -114,7 +114,7 @@ v@P += v@v * dt;
 @endcode
 @par
 The final AX command, `v@P += v@v * dt;` writes to the position attribute of
-the points @b `v@P`. Whenever position is written to in this way, the AX
+the points @b `v\@P`. Whenever position is written to in this way, the AX
 `PointExecutable` will move (re-bucket) points in PointDataGrids.
 
 @subsection axexamplepointcurlnoise Curl Noise
@@ -234,7 +234,7 @@ vec3f@vel += dt * massInverse * vec3f@force;
 @par
 Here we demonstrate how AX can be used to blend two volumes together. Note that
 only the volumes which are written to are executed over. In the below code,
-only @b `@surface_a` is written to. This means that the final blended result,
+only @b `\@surface_a` is written to. This means that the final blended result,
 stored in `surface_a`, will only be updated in `surface_a`'s topology. Should
 we want a combined blend of @b non @b overlapping areas of both surface a and b,
 we would need to activate a's topology with respect to b first.

diff --git a/doc/changes.txt b/doc/changes.txt
@@ -12,7 +12,7 @@ Bug Fixes:
   This could potentially be a problem on Windows debug builds (unconfirmed).
 - Minor fix to range in openvdb/tools/LevelSetSphere.h. This could result
   in data races for multi-threaded execution (unconfirmed) [Reported by Tommy Hinks]
-- Fixed a bug with Tree::combineExtended which wouldn't propagate the resulting active state when a destination tile overlapped a source child node.  [Reported by @frapit]
+- Fixed a bug with Tree::combineExtended which wouldn't propagate the resulting active state when a destination tile overlapped a source child node.  [Reported by \@frapit]
 - Fix unit tests failures with Blosc versions >= 1.19.0.
 
 @par
@@ -56,7 +56,7 @@ preserve ABI compatibility it might be necessary to define the macro
 <BLOCKQUOTE>
 Official release of NanoVDB, which for the first time offers GPU support for
 static sparse volumes in OpenVDB. See the
-<A HREF="https://academysoftwarefoundation.github.io/openvdb/NanoVDB_MainPage.html">documentation</A>
+<A HREF="https://www.openvdb.org/documentation/doxygen/NanoVDB_MainPage.html">documentation</A>
 for details.
 </BLOCKQUOTE>
 
@@ -488,7 +488,7 @@ a domain specific JIT (just-in-time) compiled expression language,
 providing users with a new way of interacting with OpenVDB data. AX is
 tailored towards writing highly parallelizable and customizable OpenVDB
 volume and point kernel operations. See the
-<A HREF="https://academysoftwarefoundation.github.io/openvdb/openvdbax.html">documentation</A>
+<A HREF="https://www.openvdb.org/documentation/openvdbax.html">documentation</A>
 for more.
 </BLOCKQUOTE>
 
@@ -768,7 +768,7 @@ Improvements:
 - Removed Boost::thread as a dependency of vdb_view in favour of std::thread.
 - Removed usage of boost/integer.hpp and boost/math/constants/constants.hpp,
   the latter in favour of new openvdb math constants for pi
-- Removed usage of boost/mpl/*.hpp methods in favour of new template
+- Removed usage of boost/mpl/\*.hpp methods in favour of new template
   meta-programming methods on the @vdblink::TypeList TypeList@endlink struct.
   This now supports get, front, back, contains, index, unique, popback, popfront
   and range removal of types.
@@ -1234,7 +1234,7 @@ Bug fixes:
 @par
 API changes:
 - Moved the @vdblink::CopyConstness CopyConstness@endlink metafunction from
-  @link tree/TreeIterator.h TreeIterator.h@endlink to @link Types.h@endlink.
+  @link tree/TreeIterator.h TreeIterator.h@endlink to @link Types.h Types.h@endlink.
 
 @par
 Houdini:
@@ -2199,8 +2199,8 @@ Bug fixes:
 - Fixed memory leak in a @vdblink::tools::meshToVolume tools::meshToVolume@endlink
   sub-tool (expandNarrowband).
   <I>[Reported by K&eacute;vin&nbsp;Dietrich]</I>
-- Fixed parameter type inconsistencies in @link math/Stencils.h@endlink and
-  @link tools/RayIntersector.h@endlink.
+- Fixed parameter type inconsistencies in @link math/Stencils.h math/Stencils.h@endlink
+  and @link tools/RayIntersector.h tools/RayIntersector.h@endlink.
   <I>[Contributed by K&eacute;vin&nbsp;Dietrich and Nick&nbsp;Avramoussis]</I>
 - Fixed a bug in the @vdblink::tools::VolumeToMesh VolumeToMesh@endlink tool that
   produced artifacts for adaptive surface extraction on clipped level sets.
@@ -2514,7 +2514,7 @@ Houdini:
   for material color lookups.
 - Added @vdblink::getLibraryVersionString()
   getLibraryVersionString@endlink and
-  @link OPENVDB_LIBRARY_VERSION_STRING@endlink.
+  @link OPENVDB_LIBRARY_VERSION_STRING OPENVDB_LIBRARY_VERSION_STRING@endlink.
 - Modified the mesh to volume converter to always set the grid background
   value to the exterior narrow-band width, and added finite value checks
   to narrow band parameters.

diff --git a/doc/nanovdb/doc.md b/doc/nanovdb/doc.md
@@ -2,7 +2,7 @@
 
 Welcome to the NanoVDB documentation page.
 
-* @ref NanoVDB_HowToBuild
-* @ref NanoVDB_FAQ
-* @ref NanoVDB_SourceTree
-* @ref NanoVDB_HelloWorld
+* @subpage NanoVDB_HowToBuild
+* @subpage NanoVDB_FAQ
+* @subpage NanoVDB_SourceTree
+* @subpage NanoVDB_HelloWorld
diff --git a/nanovdb/nanovdb/util/Reduce.h b/nanovdb/nanovdb/util/Reduce.h
@@ -29,6 +29,7 @@ namespace nanovdb {
 /// @return reduction
 ///
 /// @param range  RangeT can be Range<dim,T>, CoordBBox, tbb::blocked_range, blocked_range2D, or blocked_range3D.
+/// @param identity  initial value
 /// @param func   functor with signature T FuncT::operator()(const RangeT& range, const T& a) const
 /// @param join   functor with the signature T JoinT::operator()(const T& a, const T& b) const
 /// @code

diff --git a/openvdb/openvdb/README b/openvdb/openvdb/README
@@ -9,7 +9,7 @@ volumetric data discretized on a three-dimensional grid.
 For instructions on library installation and dependencies see INSTALL
 
 For documentation of the library and code examples see:
-https://academysoftwarefoundation.github.io/openvdb
+https://www.openvdb.org/documentation/doxygen
 
 For more details visit the project's home page:
 www.openvdb.org

diff --git a/openvdb/openvdb/points/PointMask.h b/openvdb/openvdb/points/PointMask.h
@@ -28,7 +28,7 @@ namespace OPENVDB_VERSION_NAME {
 namespace points {
 
 /// @brief Extract a Mask Tree from a Point Data Tree
-/// @param grid         the PointDataGrid to extract the mask from.
+/// @param tree         the PointDataTree to extract the mask from.
 /// @param filter       an optional index filter
 /// @param threaded     enable or disable threading  (threading is enabled by default)
 template <typename PointDataTreeT,

diff --git a/openvdb/openvdb/points/PointRasterizeSDF.h b/openvdb/openvdb/points/PointRasterizeSDF.h
@@ -280,6 +280,7 @@ rasterizeSmoothSpheres(const PointDataGridT& points,
 /// @param points       the point data grid to rasterize
 /// @param radius       the world space radius of every point
 /// @param searchRadius the maximum search distance of every point
+/// @param attributes   list of attributes to transfer
 /// @param halfband     the half band width
 /// @param transform    the target transform for the surface
 /// @param filter       a filter to apply to points
@@ -329,6 +330,7 @@ rasterizeSmoothSpheres(const PointDataGridT& points,
 /// @param radius       the attribute containing the world space radius
 /// @param radiusScale  the scale applied to every world space radius value
 /// @param searchRadius the maximum search distance of every point
+/// @param attributes   list of attributes to transfer
 /// @param halfband     the half band width
 /// @param transform    the target transform for the surface
 /// @param filter       a filter to apply to points

diff --git a/openvdb/openvdb/points/PointRasterizeTrilinear.h b/openvdb/openvdb/points/PointRasterizeTrilinear.h
@@ -3,7 +3,7 @@
 //
 /// @author Nick Avramoussis
 ///
-/// @file PointTransferSchemes.h
+/// @file PointRasterizeTrilinear.h
 ///
 /// @brief Transfer schemes for rasterizing point data
 ///

diff --git a/openvdb/openvdb/points/impl/PointRasterizeSDFImpl.h b/openvdb/openvdb/points/impl/PointRasterizeSDFImpl.h
@@ -3,7 +3,7 @@
 //
 /// @author Nick Avramoussis
 ///
-/// @file PointRasterizeSDF.h
+/// @file PointRasterizeSDFImpl.h
 ///
 
 #ifndef OPENVDB_POINTS_RASTERIZE_SDF_IMPL_HAS_BEEN_INCLUDED
@@ -14,6 +14,8 @@ OPENVDB_USE_VERSION_NAMESPACE
 namespace OPENVDB_VERSION_NAME {
 namespace points {
 
+/// @cond OPENVDB_DOCS_INTERNAL
+
 namespace rasterize_sdf_internal
 {
 
@@ -1045,6 +1047,7 @@ rasterizeSurface(const PointDataGridT& points,
 
 } // namespace rasterize_sdf_internal
 
+/// @endcond
 
 ///////////////////////////////////////////////////
 ///////////////////////////////////////////////////

diff --git a/openvdb/openvdb/points/impl/PointRasterizeTrilinearImpl.h b/openvdb/openvdb/points/impl/PointRasterizeTrilinearImpl.h
@@ -3,7 +3,7 @@
 //
 /// @author Nick Avramoussis
 ///
-/// @file PointTransferSchemes.h
+/// @file PointRasterizeTrilinearImpl.h
 ///
 
 #ifndef OPENVDB_POINTS_RASTERIZE_TRILINEAR_IMPL_HAS_BEEN_INCLUDED
@@ -14,6 +14,8 @@ OPENVDB_USE_VERSION_NAMESPACE
 namespace OPENVDB_VERSION_NAME {
 namespace points {
 
+/// @cond OPENVDB_DOCS_INTERNAL
+
 namespace rasterize_trilinear_internal {
 
 template <typename TreeType,
@@ -316,6 +318,8 @@ rasterizeTrilinear(const PointDataTreeT& points,
 
 } // namespace rasterize_trilinear_internal
 
+/// @endcond
+
 ///////////////////////////////////////////////////
 
 template <bool Staggered,

diff --git a/openvdb/openvdb/tree/TreeIterator.h b/openvdb/openvdb/tree/TreeIterator.h
@@ -661,7 +661,7 @@ class TreeValueIteratorBase
 
     /// @brief Return in @a node a pointer to the node over which this iterator is
     /// currently iterating or one of that node's parents, as determined by @a NodeType.
-    /// @return a null pointer if @a NodeType specifies a node at a lower level
+    /// Sets @a node to null pointer if @a NodeType specifies a node at a lower level
     /// of the tree than that given by getLevel().
     template<typename NodeType>
     void getNode(NodeType*& node) const { mValueIterList.getNode(mLevel, node); }

diff --git a/openvdb/openvdb/util/NullInterrupter.h b/openvdb/openvdb/util/NullInterrupter.h
@@ -29,14 +29,14 @@ struct NullInterrupter
     virtual ~NullInterrupter() = default;
     /// Signal the start of an interruptible operation.
     /// @param name  an optional descriptive name for the operation
-    virtual void start(const char* /*name*/ = nullptr) { }
+    virtual void start(const char* name = nullptr) { (void)name; }
     /// Signal the end of an interruptible operation.
     virtual void end() { }
     /// Check if an interruptible operation should be aborted.
     /// @param percent  an optional (when >= 0) percentage indicating
     ///     the fraction of the operation that has been completed
     /// @note this method is assumed to be thread-safe.
-    virtual bool wasInterrupted(int /*percent*/ = -1) { return false; }
+    virtual bool wasInterrupted(int percent = -1) { (void)percent; return false; }
     /// Convenience method to return a reference to the base class from a derived class.
     virtual NullInterrupter& interrupter() final {
         return static_cast<NullInterrupter&>(*this);

diff --git a/openvdb_ax/openvdb_ax/compiler/PointExecutable.h b/openvdb_ax/openvdb_ax/compiler/PointExecutable.h
@@ -123,7 +123,7 @@ class OPENVDB_AX_API PointExecutable
     size_t getGrainSize() const;
 
     /// @brief  Set attribute bindings.
-    /// @param attributeBindings A map of attribute bindings to expected names on
+    /// @param bindings A map of attribute bindings to expected names on
     ///   the geometry to be executed over. By default the AX attributes will be
     ///   bound to point attributes of the same name. Supplying bindings
     ///   for a subset of the attributes will leave the others unchanged.

diff --git a/openvdb_ax/openvdb_ax/compiler/VolumeExecutable.h b/openvdb_ax/openvdb_ax/compiler/VolumeExecutable.h
@@ -247,7 +247,7 @@ class OPENVDB_AX_API VolumeExecutable
     [[deprecated]] Index getTreeExecutionLevel() const;
 
     /// @brief  Set attribute bindings.
-    /// @param attributeBindings A map of attribute bindings to expected names on
+    /// @param bindings A map of attribute bindings to expected names on
     ///   the geometry to be executed over. By default the AX attributes will be
     ///   bound to volumes of the same name. Supplying bindings
     ///   for a subset of the attributes will leave the others unchanged.