Build and install text help alongside html (#2236)

* build text docs alongside html

also:
- capture more doc dependencies that should cause rebuilds
- move intermediate build output (doctree data) into build dir
- allow sphinx build to multitask more for faster completion times

* install text help alongside html help

* update settings in docs build action

.github/workflows/build.yml

@@ -128,14 +128,14 @@ jobs:
         python-version: 3
     - name: Install dependencies
       run: |
-        pip install 'sphinx<4.4.0'
+        pip install 'sphinx'
     - name: Clone DFHack
       uses: actions/checkout@v1
       with:
         submodules: true
     - name: Build docs
       run: |
-        sphinx-build -W --keep-going -j3 --color . docs/html
+        sphinx-build -W --keep-going -j auto --color . docs/html
     - name: Upload docs
       uses: actions/upload-artifact@v1
       with:

.gitignore

@@ -18,6 +18,7 @@ build/VC2010
 docs/_*
 docs/html/
 docs/pdf/
+docs/text/
 
 # in-place build
 build/Makefile

CMakeLists.txt

@@ -1,7 +1,7 @@
 # main project file. use it from a build sub-folder, see COMPILE for details
 
 ## some generic CMake magic
-cmake_minimum_required(VERSION 2.8.12 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.6 FATAL_ERROR)
 cmake_policy(SET CMP0048 NEW)
 project(dfhack)
 
@@ -450,37 +450,47 @@ if(BUILD_DOCS)
         message(SEND_ERROR "Sphinx not found but BUILD_DOCS enabled")
     endif()
 
-    file(GLOB SPHINX_DEPS
+    file(GLOB SPHINX_GLOB_DEPS
-        "${CMAKE_CURRENT_SOURCE_DIR}/docs/*.rst"
+        LIST_DIRECTORIES false
-        "${CMAKE_CURRENT_SOURCE_DIR}/docs/guides/*.rst"
-        "${CMAKE_CURRENT_SOURCE_DIR}/docs/changelog.txt"
-        "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_changelog.py"
         "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/*.png"
         "${CMAKE_CURRENT_SOURCE_DIR}/docs/styles/*"
-        "${CMAKE_CURRENT_SOURCE_DIR}/conf.py"
+        "${CMAKE_CURRENT_SOURCE_DIR}/data/init/*init"
-        "${CMAKE_CURRENT_SOURCE_DIR}/scripts/about.txt"
+    )
-        "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/about.txt"
+    file(GLOB_RECURSE SPHINX_GLOB_RECURSE_DEPS
+        "${CMAKE_CURRENT_SOURCE_DIR}/*.rst"
+        "${CMAKE_CURRENT_SOURCE_DIR}/changelog.txt"
+    )
+    list(FILTER SPHINX_GLOB_RECURSE_DEPS
+        EXCLUDE REGEX "docs/_"
     )
     file(GLOB_RECURSE SPHINX_SCRIPT_DEPS
         "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua"
         "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.rb"
+        "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.txt"
     )
-    set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS}
+    set(SPHINX_DEPS ${SPHINX_GLOB_DEPS} ${SPHINX_GLOB_RECURSE_DEPS} ${SPHINX_SCRIPT_DEPS}
-        "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE.rst"
         "${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.txt"
+        "${CMAKE_CURRENT_SOURCE_DIR}/conf.py"
+        "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_changelog.py"
     )
 
     set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo")
     set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE)
     add_custom_command(OUTPUT ${SPHINX_OUTPUT}
         COMMAND ${SPHINX_EXECUTABLE}
-            -a -E -q -b html
+            -q -b html -d "${CMAKE_BINARY_DIR}/docs/html"
             "${CMAKE_CURRENT_SOURCE_DIR}"
             "${CMAKE_CURRENT_SOURCE_DIR}/docs/html"
-            -w "${CMAKE_CURRENT_SOURCE_DIR}/docs/_sphinx-warnings.txt"
+            -w "${CMAKE_BINARY_DIR}/docs/html/_sphinx-warnings.txt"
-            -j 2
+            -j auto
+        COMMAND ${SPHINX_EXECUTABLE}
+            -q -b text -d "${CMAKE_BINARY_DIR}/docs/text"
+            "${CMAKE_CURRENT_SOURCE_DIR}"
+            "${CMAKE_CURRENT_SOURCE_DIR}/docs/text"
+            -w "${CMAKE_BINARY_DIR}/docs/text/_sphinx-warnings.txt"
+            -j auto
         DEPENDS ${SPHINX_DEPS}
-        COMMENT "Building HTML documentation with Sphinx"
+        COMMENT "Building documentation with Sphinx"
     )
 
     add_custom_target(dfhack_docs ALL
@@ -493,6 +503,8 @@ if(BUILD_DOCS)
 
     install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/html/
         DESTINATION ${DFHACK_USERDOC_DESTINATION}/docs)
+    install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/text/
+        DESTINATION ${DFHACK_USERDOC_DESTINATION}/docs)
     install(FILES docs/_auto/news.rst docs/_auto/news-dev.rst DESTINATION ${DFHACK_USERDOC_DESTINATION})
     install(FILES "README.html" DESTINATION "${DFHACK_DATA_DESTINATION}")
 endif()