docs: build and package new Sphinx docs on macOS

.github/workflows/cmake.yml

@@ -26,8 +26,6 @@ jobs:
     - name: Linux Build
       if: runner.os == 'Linux'
       run: |
-          sudo apt-get update
-          sudo apt-get install -y groff
           ./build-linux-64.sh
 
     - name: macOS Build

CMakeLists.txt

@@ -3,6 +3,8 @@ cmake_policy(SET CMP0028 NEW)
 
 project (ericw-tools)
 
+set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
+
 # Grab the git describe output and store it in GIT_DESCRIBE
 # Thanks to http://xit0.org/2013/04/cmake-use-git-branch-and-commit-details-in-project/
 execute_process(
@@ -92,6 +94,7 @@ endif ()
 
 add_subdirectory(qbsp)
 add_subdirectory(vis)
+add_subdirectory(docs)
 
 install(FILES README.md DESTINATION bin)
 install(FILES changelog.md DESTINATION bin)

README.md

@@ -40,12 +40,12 @@ source code.
 
 ## Compiling
 
-Dependencies: Embree 3.0+, TBB (TODO: version?), groff (for building manuals)
+Dependencies: Embree 3.0+, TBB (TODO: version?), Sphinx (for building manuals)
 
 ### Ubuntu
 
 ```
-sudo apt install libembree-dev libtbb-dev groff cmake build-essential g++
+sudo apt install libembree-dev libtbb-dev python3-sphinx cmake build-essential g++
 git clone --recursive https://github.com/ericwa/ericw-tools
 cd ericw-tools
 mkdir build
@@ -58,6 +58,8 @@ cmake ..
 Example using vcpkg (32-bit build):
 
 ```
+# TODO: sphinx installation
+
 git clone --recursive https://github.com/ericwa/ericw-tools
 cd ericw-tools
 git clone https://github.com/microsoft/vcpkg
@@ -78,6 +80,7 @@ cmake .. -DCMAKE_TOOLCHAIN_FILE="$(pwd)/../vcpkg/scripts/buildsystems/vcpkg.cmak
 
 ```
 brew install embree tbb
+python3 -m pip install sphinx_rtd_theme
 git clone --recursive https://github.com/ericwa/ericw-tools
 cd ericw-tools
 mkdir build

build-osx.sh

@@ -3,6 +3,8 @@
 # for sha256sum, used by the tests
 brew install coreutils
 
+python3 -m pip install sphinx_rtd_theme
+
 BUILD_DIR=build-osx
 EMBREE_ZIP="https://github.com/embree/embree/releases/download/v3.13.0/embree-3.13.0.x86_64.macosx.zip"
 

cmake/FindSphinx.cmake

@@ -0,0 +1,14 @@
+# From:
+# https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
+
+#Look for an executable called sphinx-build
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build
+             DOC "Path to sphinx-build executable")
+
+include(FindPackageHandleStandardArgs)
+
+#Handle standard arguments to find_package like REQUIRED and QUIET
+find_package_handle_standard_args(Sphinx
+                                  "Failed to find sphinx-build executable"
+                                  SPHINX_EXECUTABLE)

docs/CMakeLists.txt

@@ -0,0 +1,18 @@
+# From:
+# https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
+
+find_package(Sphinx REQUIRED)
+
+if (Sphinx_FOUND)
+    set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
+    set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/docs/sphinx)
+
+    add_custom_target(Sphinx ALL
+                      COMMAND
+                      ${SPHINX_EXECUTABLE} -b html
+                      ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                      COMMENT "Generating documentation with Sphinx")
+
+    install(DIRECTORY ${SPHINX_BUILD}/ DESTINATION doc)
+endif()