Rename "docs" to "website" (AcademySoftwareFoundation#338)

* Rename "docs" to "website" "website" is a more accurate term than "docs", so: - The source lives in the ``website`` subdirectory (was ``docs``) - The CMake option is now ``BUILD_WEBSITE`` (was ``BUILD_DOCS``) - The CMake target is now ``website`` (was ``docs``) - There's no longer a CMake option to install the docs, since copying the ``.html`` to the install location is pointless. The ``INSTALL_DOCS`` option has been removed. Signed-off-by: Cary Phillips <cary@ilm.com> * change $ to % in install.rst Signed-off-by: Cary Phillips <cary@ilm.com> * rename docs to website in ci_workflows.yml Signed-off-by: Cary Phillips <cary@ilm.com> * mention sphinx_press_theme and rst Signed-off-by: Cary Phillips <cary@ilm.com> --------- Signed-off-by: Cary Phillips <cary@ilm.com>
cary-ilm · Jan 23, 2024 · b7894fe · b7894fe
1 parent 60a69b2
commit b7894fe
Show file tree

Hide file tree

Showing 82 changed files with 50 additions and 38 deletions.
diff --git a/.github/workflows/ci_workflow.yml b/.github/workflows/ci_workflow.yml
@@ -301,7 +301,7 @@ jobs:
           ./bin/ImathTest
           # Confirm the examples compile and execute
           rm -rf bin CMakeCache.txt CMakeFiles cmake_install.cmake Makefile
-          cmake ../docs/examples \
+          cmake ../website/examples \
                 -DCMAKE_PREFIX_PATH=../../_install \
                 -DCMAKE_BUILD_TYPE=${{ matrix.build-type }} \
                 -DCMAKE_CXX_STANDARD=${{ matrix.cxx-standard }} \
@@ -609,14 +609,14 @@ jobs:
         shell: bash
         working-directory: _build
 
-  Docs:
+  Website:
 
     # Build the documentation, using a process that mimics the readthedoc build.
     #
     # Note that this job does not actually build Imath libraries,
     # it just runs doxygen and sphinx.
 
-    name: 'Docs'
+    name: 'Website'
     runs-on: ubuntu-latest
 
     steps:
@@ -628,14 +628,14 @@ jobs:
         # Need help2man for tool manpages
         run: sudo apt-get install -y doxygen help2man
       - name: Install sphinx requirements
-        run: pip3 install -r docs/requirements.txt
+        run: pip3 install -r website/requirements.txt
       - name: Configure
-        run: cmake .. -DBUILD_DOCS='ON'
+        run: cmake .. -DBUILD_WEBSITE='ON'
         working-directory: _build
       - name: Build
         run: |
           cmake --build . \
-                --target docs \
+                --target website \
                 --config Release
         working-directory: _build
 
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -14,8 +14,8 @@ build:
     python: "3.9"
 
 sphinx:
-  configuration: docs/conf.py
+  configuration: website/conf.py
 
 python:
   install:
-    - requirements: docs/requirements.txt
+    - requirements: website/requirements.txt
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -73,10 +73,9 @@ if (PYTHON)
   add_subdirectory(src/python)
 endif()
 
-option(BUILD_DOCS "Set ON to build readthedocs documentation")
-if (BUILD_DOCS AND NOT IMATH_IS_SUBPROJECT)
-  option(INSTALL_DOCS "Set ON to install html documentation" ON)
-  add_subdirectory(docs)
+option(BUILD_WEBSITE "Set ON to build the readthedocs website source")
+if (BUILD_WEBSITE AND NOT IMATH_IS_SUBPROJECT)
+  add_subdirectory(website)
 endif()
 
 # If you want to use ctest to configure, build and

diff --git a/docs/CMakeLists.txt → website/CMakeLists.txt b/docs/CMakeLists.txt → website/CMakeLists.txt
@@ -38,11 +38,5 @@ add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
                    MAIN_DEPENDENCY conf.py
                    COMMENT "Generating documentation with Sphinx")
 
-add_custom_target(docs ALL DEPENDS ${SPHINX_INDEX_FILE} ${DOXYGEN_INDEX_FILE})
-
-# Add an install target to install the docs
-if(INSTALL_DOCS)
-    include(GNUInstallDirs)
-    install(DIRECTORY ${SPHINX_BUILD}
-    DESTINATION ${CMAKE_INSTALL_DOCDIR})
-endif()
+add_custom_target(website ALL DEPENDS ${SPHINX_INDEX_FILE} ${DOXYGEN_INDEX_FILE})
+
diff --git a/docs/Doxyfile.in → website/Doxyfile.in b/docs/Doxyfile.in → website/Doxyfile.in
diff --git a/docs/Makefile → website/Makefile b/docs/Makefile → website/Makefile
diff --git a/docs/PortingGuide.rst → website/PortingGuide.rst b/docs/PortingGuide.rst → website/PortingGuide.rst
diff --git a/docs/PortingGuide2-3.md → website/PortingGuide2-3.md b/docs/PortingGuide2-3.md → website/PortingGuide2-3.md
diff --git a/docs/SymbolVisibility.rst → website/SymbolVisibility.rst b/docs/SymbolVisibility.rst → website/SymbolVisibility.rst
diff --git a/docs/about.rst → website/about.rst b/docs/about.rst → website/about.rst
diff --git a/docs/classes.rst → website/classes.rst b/docs/classes.rst → website/classes.rst
diff --git a/docs/classes/Box.rst → website/classes/Box.rst b/docs/classes/Box.rst → website/classes/Box.rst
diff --git a/docs/classes/Color3.rst → website/classes/Color3.rst b/docs/classes/Color3.rst → website/classes/Color3.rst
diff --git a/docs/classes/Color4.rst → website/classes/Color4.rst b/docs/classes/Color4.rst → website/classes/Color4.rst
diff --git a/docs/classes/Euler.rst → website/classes/Euler.rst b/docs/classes/Euler.rst → website/classes/Euler.rst
diff --git a/docs/classes/Frustum.rst → website/classes/Frustum.rst b/docs/classes/Frustum.rst → website/classes/Frustum.rst
diff --git a/docs/classes/Interval.rst → website/classes/Interval.rst b/docs/classes/Interval.rst → website/classes/Interval.rst
diff --git a/docs/classes/Line3.rst → website/classes/Line3.rst b/docs/classes/Line3.rst → website/classes/Line3.rst
diff --git a/docs/classes/Matrix22.rst → website/classes/Matrix22.rst b/docs/classes/Matrix22.rst → website/classes/Matrix22.rst
diff --git a/docs/classes/Matrix33.rst → website/classes/Matrix33.rst b/docs/classes/Matrix33.rst → website/classes/Matrix33.rst
diff --git a/docs/classes/Matrix44.rst → website/classes/Matrix44.rst b/docs/classes/Matrix44.rst → website/classes/Matrix44.rst
diff --git a/docs/classes/Plane3.rst → website/classes/Plane3.rst b/docs/classes/Plane3.rst → website/classes/Plane3.rst
diff --git a/docs/classes/Quat.rst → website/classes/Quat.rst b/docs/classes/Quat.rst → website/classes/Quat.rst
diff --git a/docs/classes/Rand32.rst → website/classes/Rand32.rst b/docs/classes/Rand32.rst → website/classes/Rand32.rst
diff --git a/docs/classes/Rand48.rst → website/classes/Rand48.rst b/docs/classes/Rand48.rst → website/classes/Rand48.rst
diff --git a/docs/classes/Shear6.rst → website/classes/Shear6.rst b/docs/classes/Shear6.rst → website/classes/Shear6.rst
diff --git a/docs/classes/Sphere3.rst → website/classes/Sphere3.rst b/docs/classes/Sphere3.rst → website/classes/Sphere3.rst
diff --git a/docs/classes/Vec2.rst → website/classes/Vec2.rst b/docs/classes/Vec2.rst → website/classes/Vec2.rst
diff --git a/docs/classes/Vec3.rst → website/classes/Vec3.rst b/docs/classes/Vec3.rst → website/classes/Vec3.rst
diff --git a/docs/classes/Vec4.rst → website/classes/Vec4.rst b/docs/classes/Vec4.rst → website/classes/Vec4.rst
diff --git a/docs/classes/float.rst → website/classes/float.rst b/docs/classes/float.rst → website/classes/float.rst
diff --git a/docs/classes/half.rst → website/classes/half.rst b/docs/classes/half.rst → website/classes/half.rst
diff --git a/docs/classes/half_c.rst → website/classes/half_c.rst b/docs/classes/half_c.rst → website/classes/half_c.rst
diff --git a/docs/classes/half_class.rst → website/classes/half_class.rst b/docs/classes/half_class.rst → website/classes/half_class.rst
diff --git a/docs/classes/half_conversion.rst → website/classes/half_conversion.rst b/docs/classes/half_conversion.rst → website/classes/half_conversion.rst
diff --git a/docs/classes/half_limits.rst → website/classes/half_limits.rst b/docs/classes/half_limits.rst → website/classes/half_limits.rst
diff --git a/docs/concepts.rst → website/concepts.rst b/docs/concepts.rst → website/concepts.rst
diff --git a/docs/conf.py → website/conf.py b/docs/conf.py → website/conf.py
diff --git a/docs/examples/Box.cpp → website/examples/Box.cpp b/docs/examples/Box.cpp → website/examples/Box.cpp
diff --git a/docs/examples/CMakeLists.txt → website/examples/CMakeLists.txt b/docs/examples/CMakeLists.txt → website/examples/CMakeLists.txt
diff --git a/docs/examples/Color3.cpp → website/examples/Color3.cpp b/docs/examples/Color3.cpp → website/examples/Color3.cpp
diff --git a/docs/examples/Color4.cpp → website/examples/Color4.cpp b/docs/examples/Color4.cpp → website/examples/Color4.cpp
diff --git a/docs/examples/Euler.cpp → website/examples/Euler.cpp b/docs/examples/Euler.cpp → website/examples/Euler.cpp
diff --git a/docs/examples/Frustum.cpp → website/examples/Frustum.cpp b/docs/examples/Frustum.cpp → website/examples/Frustum.cpp
diff --git a/docs/examples/Interval.cpp → website/examples/Interval.cpp b/docs/examples/Interval.cpp → website/examples/Interval.cpp
diff --git a/docs/examples/Line3.cpp → website/examples/Line3.cpp b/docs/examples/Line3.cpp → website/examples/Line3.cpp
diff --git a/docs/examples/Matrix22.cpp → website/examples/Matrix22.cpp b/docs/examples/Matrix22.cpp → website/examples/Matrix22.cpp
diff --git a/docs/examples/Matrix33.cpp → website/examples/Matrix33.cpp b/docs/examples/Matrix33.cpp → website/examples/Matrix33.cpp
diff --git a/docs/examples/Matrix44.cpp → website/examples/Matrix44.cpp b/docs/examples/Matrix44.cpp → website/examples/Matrix44.cpp
diff --git a/docs/examples/Plane3.cpp → website/examples/Plane3.cpp b/docs/examples/Plane3.cpp → website/examples/Plane3.cpp
diff --git a/docs/examples/Quat.cpp → website/examples/Quat.cpp b/docs/examples/Quat.cpp → website/examples/Quat.cpp
diff --git a/docs/examples/Shear6.cpp → website/examples/Shear6.cpp b/docs/examples/Shear6.cpp → website/examples/Shear6.cpp
diff --git a/docs/examples/Sphere3.cpp → website/examples/Sphere3.cpp b/docs/examples/Sphere3.cpp → website/examples/Sphere3.cpp
diff --git a/docs/examples/Vec2.cpp → website/examples/Vec2.cpp b/docs/examples/Vec2.cpp → website/examples/Vec2.cpp
diff --git a/docs/examples/Vec3.cpp → website/examples/Vec3.cpp b/docs/examples/Vec3.cpp → website/examples/Vec3.cpp
diff --git a/docs/examples/Vec4.cpp → website/examples/Vec4.cpp b/docs/examples/Vec4.cpp → website/examples/Vec4.cpp
diff --git a/docs/examples/gl.cpp → website/examples/gl.cpp b/docs/examples/gl.cpp → website/examples/gl.cpp
diff --git a/docs/examples/half.c → website/examples/half.c b/docs/examples/half.c → website/examples/half.c
diff --git a/docs/examples/half.cpp → website/examples/half.cpp b/docs/examples/half.cpp → website/examples/half.cpp
diff --git a/docs/examples/intro.cpp → website/examples/intro.cpp b/docs/examples/intro.cpp → website/examples/intro.cpp
diff --git a/docs/examples/main.cpp → website/examples/main.cpp b/docs/examples/main.cpp → website/examples/main.cpp
diff --git a/docs/fixmanpages.sh → website/fixmanpages.sh b/docs/fixmanpages.sh → website/fixmanpages.sh
diff --git a/docs/functions.rst → website/functions.rst b/docs/functions.rst → website/functions.rst
diff --git a/docs/functions/box.rst → website/functions/box.rst b/docs/functions/box.rst → website/functions/box.rst
diff --git a/docs/functions/color.rst → website/functions/color.rst b/docs/functions/color.rst → website/functions/color.rst
diff --git a/docs/functions/frame.rst → website/functions/frame.rst b/docs/functions/frame.rst → website/functions/frame.rst
diff --git a/docs/functions/gl.rst → website/functions/gl.rst b/docs/functions/gl.rst → website/functions/gl.rst
diff --git a/docs/functions/glu.rst → website/functions/glu.rst b/docs/functions/glu.rst → website/functions/glu.rst
diff --git a/docs/functions/line.rst → website/functions/line.rst b/docs/functions/line.rst → website/functions/line.rst
diff --git a/docs/functions/matrix.rst → website/functions/matrix.rst b/docs/functions/matrix.rst → website/functions/matrix.rst
diff --git a/docs/functions/random.rst → website/functions/random.rst b/docs/functions/random.rst → website/functions/random.rst
diff --git a/docs/functions/roots.rst → website/functions/roots.rst b/docs/functions/roots.rst → website/functions/roots.rst
diff --git a/docs/functions/vec.rst → website/functions/vec.rst b/docs/functions/vec.rst → website/functions/vec.rst
diff --git a/docs/images/imath-fav.ico → website/images/imath-fav.ico b/docs/images/imath-fav.ico → website/images/imath-fav.ico
diff --git a/docs/images/imath-logo-black.png → website/images/imath-logo-black.png b/docs/images/imath-logo-black.png → website/images/imath-logo-black.png
diff --git a/docs/images/imath-logo-blue.png → website/images/imath-logo-blue.png b/docs/images/imath-logo-blue.png → website/images/imath-logo-blue.png
diff --git a/docs/images/imath-logo-white.png → website/images/imath-logo-white.png b/docs/images/imath-logo-white.png → website/images/imath-logo-white.png
diff --git a/docs/index.rst → website/index.rst b/docs/index.rst → website/index.rst
diff --git a/docs/install.rst → website/install.rst b/docs/install.rst → website/install.rst
@@ -69,11 +69,12 @@ To build via CMake, you need to first identify three directories:
    libraries and headers, referred to below as ``$installdir``.  
 
 To build:
+
 .. code-block::
 
-    $ cd $builddir
-    $ cmake $srcdir --install-prefix $installdir
-    $ cmake --build $builddir --target install --config Release
+    % cd $builddir
+    % cmake $srcdir --install-prefix $installdir
+    % cmake --build $builddir --target install --config Release
 
 Note that the CMake configuration prefers to apply an out-of-tree
 build process, since there may be multiple build configurations
@@ -102,7 +103,7 @@ can specify a local install directory to cmake via the
 
 .. code-block::
 
-    $ cmake .. -DCMAKE_INSTALL_PREFIX=$Imath_install_directory
+    % cmake .. -DCMAKE_INSTALL_PREFIX=$Imath_install_directory
 
 Library Names
 -------------
@@ -141,27 +142,45 @@ See the :doc:`PortingGuide` for details about differences from previous
 releases and how to address them. Also refer to the porting guide for
 details about changes to Imath.
 
-Building the Documentation
---------------------------
+Building the Website
+--------------------
 
 The Imath technical documentation at `https://imath.readthedocs.io
 <https://imath.readthedocs.io>`_ is generated via `Sphinx
 <https://www.sphinx-doc.org>`_ with the `Breathe
 <https://breathe.readthedocs.io>`_ extension using information
-extracted from header comments by `Doxygen <https://www.doxygen.nl>`_.
-
-To build the documentation locally from the source headers and
-``.rst`` files, set the CMake option ``BUILD_DOCS=ON``. This adds
-``Doxygen`` and ``Sphinx`` CMake targets and enables building the docs
-by default.  generation is off by default.
-
-Building the documentation requires that ``sphinx``, ``breathe``, and
+extracted from header comments by `Doxygen <https://www.doxygen.nl>`_,
+using the `sphinx-press-theme
+<https://pypi.org/project/sphinx-press-theme>`_, and is hosted by
+`readthedocs <https://readthedocs.org/projects/openexr>`_. The website
+source is in `restructured text
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
+in the ``website`` directory.
+
+To build the website locally from the source headers and
+``.rst`` files, set the CMake option ``BUILD_WEBSITE=ON``. This adds
+``website`` CMake target. Generation is off by default.
+
+Building the website requires that ``sphinx``, ``breathe``, and
 ``doxygen`` are installed. It further requires the `sphinx-press-theme
-<https://pypi.org/project/sphinx-press-theme>`_, as indicated in the
-`requirements.txt
+<https://pypi.org/project/sphinx-press-theme>`_. Complete dependencies are
+described in the `requirements.txt
 <https://github.com/AcademySoftwareFoundation/imath/blob/main/docs/requirements.txt>`_
 file.
 
+On Debian/Ubuntu Linux:
+
+.. code-block::
+
+    % apt-get install doxygen python3-sphinx
+    % pip3 install breathe
+    % pip3 install sphinx_press_theme
+   
+    % mkdir _build
+    % cd _build
+    % cmake .. -DBUILD_WEBSITE=ON
+    % cmake --build . --target website 
+
 CMake Build-time Configuration Options
 --------------------------------------
 
@@ -171,7 +190,7 @@ variables, run:
 
 .. code-block::
 
-    $ cmake -LAH $imath_source_directory
+    % cmake -LAH $imath_source_directory
 
 You can customize these options three ways:
 
@@ -306,5 +325,5 @@ initial generation:
 
 .. code-block::
 
-    $ cmake -G “Ninja” ..
+    % cmake -G “Ninja” ..
 
diff --git a/docs/license.rst → website/license.rst b/docs/license.rst → website/license.rst
diff --git a/docs/requirements.txt → website/requirements.txt b/docs/requirements.txt → website/requirements.txt
diff --git a/docs/toc_redirect.rst → website/toc_redirect.rst b/docs/toc_redirect.rst → website/toc_redirect.rst