Build and deploy TriBITS documentation with Sphinx (#386)

.github/workflows/deploy_docs.yml

@@ -0,0 +1,39 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  build-and-deploy-docs:
+
+    runs-on: ubuntu-latest
+    env:
+      working-directory: ./tribits/doc/sphinx
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.9'
+          architecture: 'x64'
+      - name: Display Python version
+        run: |
+          python -c "import sys; print(sys.version)"
+          python3 -c "import sys; print(sys.version)"
+      - name: Install Python dependencies
+        run: |
+          pip3 install sphinx sphinx-rtd-theme
+      - name: Build documentation
+        working-directory: ${{env.working-directory}}
+        run: python3 sphinx_rst_generator.py
+      - name: Generate nojekyll file
+        working-directory: ${{env.working-directory}}/combined_docs
+        run: touch .nojekyll
+      - name: Deploy docs
+        uses: JamesIves/[email protected]
+        with:
+          branch: deploy-doc-site
+          folder: ${{env.working-directory}}/combined_docs
+          clean: true

.gitignore

@@ -20,3 +20,9 @@ build/
 
 # Ignore the standard local gitdist override file
 /.gitdist
+
+# Python environment
+venv
+
+# Pycharm settings
+.idea

test/doc/CMakeLists.txt

@@ -3,6 +3,17 @@ advanced_set( ${PROJECT_NAME}_ENABLE_DOC_GENERATION_TESTS OFF
   "Enable testing for the build of the documentation.  Requries docutils and will blow away and rebuild the existing documentation in the source tree since the documentation builds in place." )
 
 
+tribits_add_advanced_test( sphinx_rst_generator_UnitTests
+  OVERALL_WORKING_DIRECTORY TEST_NAME
+  OVERALL_NUM_MPI_PROCS 1
+  EXCLUDE_IF_NOT_TRUE HAS_PYTHON3
+  TEST_0 CMND ${PYTHON_EXECUTABLE}
+    ARGS ${CMAKE_CURRENT_SOURCE_DIR}/sphinx_rst_generator_UnitTests.py -v
+    PASS_REGULAR_EXPRESSION "OK"
+    ALWAYS_FAIL_ON_NONZERO_RETURN
+  )
+
+
 tribits_add_advanced_test( build_docs
   EXCLUDE_IF_NOT_TRUE ${PROJECT_NAME}_ENABLE_DOC_GENERATION_TESTS
     GIT_EXECUTABLE
@@ -25,4 +36,56 @@ tribits_add_advanced_test( build_docs
     ARGS ${PROJECT_SOURCE_DIR}/tribits/doc/guides/maintainers_guide/TribitsMaintainersGuide.html
     PASS_REGULAR_EXPRESSION guides/maintainers_guide/TribitsMaintainersGuide.html
     ALWAYS_FAIL_ON_NONZERO_RETURN
+  ADDED_TEST_NAME_OUT build_docs_test_name
   )
+
+
+tribits_add_advanced_test( build_sphinx_docs
+  EXCLUDE_IF_NOT_TRUE ${PROJECT_NAME}_ENABLE_DOC_GENERATION_TESTS
+    GIT_EXECUTABLE
+  OVERALL_NUM_MPI_PROCS 1
+  TEST_0 MESSAGE "Clean out any prior build of the docs"
+    CMND ${GIT_EXECUTABLE} ARGS clean -xdf
+    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/tribits/doc
+    SKIP_CLEAN_WORKING_DIRECTORY  # Don't delete our source tree!
+  TEST_1 MESSAGE "Build the sphinx documentation"
+    CMND bash ARGS ${PROJECT_SOURCE_DIR}/tribits/doc/sphinx/build_sphinx_docs.sh
+  TEST_2 CMND ls
+    ARGS ${PROJECT_SOURCE_DIR}/tribits/doc/sphinx/combined_docs/index.html
+    PASS_REGULAR_EXPRESSION sphinx/combined_docs/index.html
+    ALWAYS_FAIL_ON_NONZERO_RETURN
+  TEST_3 CMND ls
+    ARGS ${PROJECT_SOURCE_DIR}/tribits/doc/sphinx/combined_docs/build_ref/index.html
+    PASS_REGULAR_EXPRESSION sphinx/combined_docs/build_ref/index.html
+    ALWAYS_FAIL_ON_NONZERO_RETURN
+  TEST_4 CMND ls
+    ARGS ${PROJECT_SOURCE_DIR}/tribits/doc/sphinx/combined_docs/users_guide/index.html
+    PASS_REGULAR_EXPRESSION sphinx/combined_docs/users_guide/index.html
+    ALWAYS_FAIL_ON_NONZERO_RETURN
+  TEST_5 CMND ls
+    ARGS ${PROJECT_SOURCE_DIR}/tribits/doc/sphinx/combined_docs/maintainers_guide/index.html
+    PASS_REGULAR_EXPRESSION sphinx/combined_docs/maintainers_guide/index.html
+    ALWAYS_FAIL_ON_NONZERO_RETURN
+  TEST_6 MESSAGE "Rebuld the sphinx documentation to show you can without error"
+    CMND bash ARGS ${PROJECT_SOURCE_DIR}/tribits/doc/sphinx/build_sphinx_docs.sh
+  ADDED_TEST_NAME_OUT build_sphinx_docs_test_name
+  )
+
+if (build_docs_test_name AND build_sphinx_docs_test_name)
+  set_tests_properties( ${build_sphinx_docs_test_name}
+    PROPERTIES DEPENDS ${build_docs_test_name})
+  # Above sets a dependency of testing the build the sphinx documentation to
+  # come after testing the build of the regular docutils documentation.  The
+  # latter does not really depend on the fommer but both of these clean out
+  # the uncommitted files under tribits/doc/ and we don't want these two tests
+  # stomping on each other.  We also don't want to label these two tests with
+  # RUN_SERIAL because they take a long time to run and we don't want to stop
+  # other TriBITS tests from running at the same time as these two.
+endif()
+
+
+if (PYTHON_VERSION_MAJOR GREATER_EQUAL 3)
+  set(HAS_PYTHON3 TRUE)
+else()
+  set(HAS_PYTHON3 FALSE)
+endif()

test/doc/FindTestDocDir.py

@@ -0,0 +1,48 @@
+# @HEADER
+# ************************************************************************
+#
+#            TriBITS: Tribal Build, Integrate, and Test System
+#                    Copyright 2013 Sandia Corporation
+#
+# Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
+# the U.S. Government retains certain rights in this software.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# 1. Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the Corporation nor the names of the
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
+# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ************************************************************************
+# @HEADER
+
+import os
+import sys
+
+testDocDir = os.path.dirname(os.path.abspath(__file__))
+tribitsDir = os.path.abspath(os.path.join(testDocDir,"../../tribits"))
+docSphinxDir = os.path.join(tribitsDir,"doc","sphinx")
+pythonUtilsDir = os.path.join(tribitsDir,"python_utils")
+
+sys.path = [docSphinxDir, pythonUtilsDir] + sys.path

test/doc/data/TribitsGuidesBody.rst

@@ -0,0 +1,23 @@
+This is a stand-in for the TribitsGuidesBody.rst file with indented includes.
+
+Something something:
+
+.. include:: ../../examples/TribitsExampleProject/ProjectName.cmake
+   :literal:
+
+4) Add custom CTest -S driver scripts.
+
+  For driving different builds and tests, one needs to set up one or more
+  CTest -S driver scripts.  There are various ways to do this but a simple
+  approach that avoids duplication is to first create a file like
+  ``TribitsExampleProject/cmake/ctest/TribitsExProjCTestDriver.cmake``:
+
+  .. include:: ../../examples/TribitsExampleProject/cmake/ctest/TribitsExProjCTestDriver.cmake
+     :literal:
+
+  and then create a set of CTest -S driver scripts that uses that file.  One
+  example is the file
+  ``TribitsExampleProject/cmake/ctest/general_gcc/ctest_serial_debug.cmake``:
+
+  .. include:: ../../examples/TribitsExampleProject/cmake/ctest/general_gcc/ctest_serial_debug.cmake
+     :literal:

test/doc/sphinx_rst_generator_UnitTests.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# @HEADER
+# ************************************************************************
+#
+#            TriBITS: Tribal Build, Integrate, and Test System
+#                    Copyright 2013 Sandia Corporation
+#
+# Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
+# the U.S. Government retains certain rights in this software.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# 1. Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the Corporation nor the names of the
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
+# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ************************************************************************
+# @HEADER
+
+#################################################
+# Unit testing code for sphinx_rst_generator.py #
+#################################################
+
+import unittest
+
+from FindTestDocDir import *
+import sphinx_rst_generator as SRG
+
+
+#
+# Unit tests for sphinx_rst_generator.change_paths_and_get_includes()
+#
+
+
+tribitsGuideBodyCopied_expected = \
+r"""This is a stand-in for the TribitsGuidesBody.rst file with indented includes.
+
+Something something:
+
+.. include:: ../copied_files/ProjectName.cmake
+   :literal:
+
+4) Add custom CTest -S driver scripts.
+
+  For driving different builds and tests, one needs to set up one or more
+  CTest -S driver scripts.  There are various ways to do this but a simple
+  approach that avoids duplication is to first create a file like
+  ``TribitsExampleProject/cmake/ctest/TribitsExProjCTestDriver.cmake``:
+
+  .. include:: ../copied_files/TribitsExProjCTestDriver.cmake
+     :literal:
+
+  and then create a set of CTest -S driver scripts that uses that file.  One
+  example is the file
+  ``TribitsExampleProject/cmake/ctest/general_gcc/ctest_serial_debug.cmake``:
+
+  .. include:: ../copied_files/ctest_serial_debug.cmake
+     :literal:
+"""
+
+
+class test_change_paths_and_get_includes(unittest.TestCase):
+
+
+  def test_1(self):
+    src_file_path = os.path.join(testDocDir,'data')
+    source_file = os.path.join(src_file_path,'TribitsGuidesBody.rst')
+    start_path = os.path.join(tribitsDir,'doc','sphinx','users_guide')
+    rst_dir = os.path.join(tribitsDir,'doc','sphinx','copied_files')
+    (abs_path_str, include_file_list) = SRG.change_paths_and_get_includes(
+      source_file=source_file, src_file_path=src_file_path,
+      start_path=start_path, rst_dir=rst_dir, copy_file=True)
+    #print("abs_path_str = "+str(abs_path_str))
+    #print("include_file_list = "+str(include_file_list))
+    self.maxDiff = None
+    self.assertEqual(abs_path_str, tribitsGuideBodyCopied_expected)
+    include_file_list_expected = set()
+    self.assertEqual(include_file_list, include_file_list_expected)
+
+
+if __name__ == '__main__':
+  unittest.main()

tribits/doc/build_ref/Makefile

@@ -15,17 +15,19 @@ EXTRA_FILES = \
 # NOTE: We *don't* want to rebuild the file if only the version has changed we
 # don't add a dependency on TribitsGitVersion.txt!
 
-all: $(BASE_NAME).rst $(BASE_NAME).html $(BASE_NAME).pdf
-
-$(BASE_NAME).pdf: $(BASE_NAME).html 
-
-$(BASE_NAME).html: $(BASE_NAME).rst
-
-$(BASE_NAME).rst: $(EXTRA_FILES)
+CREATE_PROJECT_BUILD_REF_CMND = \
 	./create-project-build-ref.py \
 	--project-name="<Project>" \
 	--project-template-file=TribitsBuildReferenceTemplate.rst \
-	--file-base=TribitsBuildReference \
+	--file-base=TribitsBuildReference
+
+all: $(EXTRA_FILES)
+	$(CREATE_PROJECT_BUILD_REF_CMND) \
+	$(EXTRA_ARGS)
+
+$(BASE_NAME).rst: $(EXTRA_FILES)
+	$(CREATE_PROJECT_BUILD_REF_CMND) \
+	--generate-html= --generate-latex= --generate-pdf= \
 	$(EXTRA_ARGS)
 
 clean:

tribits/doc/build_ref/create-build-ref.sh

@@ -40,6 +40,7 @@ if [[ "${skip_final_generation}" == "0" ]] ; then
   make
 else
   echo
-  echo "Skipping geneation of HTML and PDF files on request!"
+  echo "Only generating the file TribitsBuildReference.rst on request!"
   echo
+  make TribitsBuildReference.rst
 fi

tribits/doc/sphinx/build_ref/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)