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
develop
Myk 2022-07-05 12:21:41 -07:00 committed by myk002
parent 28e15162a5
commit f1cb9b9a83
No known key found for this signature in database
GPG Key ID: 8A39CA0FA0C16E78
3 changed files with 30 additions and 17 deletions

@ -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:

1
.gitignore vendored

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

@ -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
"${CMAKE_CURRENT_SOURCE_DIR}/docs/*.rst"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/guides/*.rst"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/changelog.txt"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_changelog.py"
file(GLOB SPHINX_GLOB_DEPS
LIST_DIRECTORIES false
"${CMAKE_CURRENT_SOURCE_DIR}/docs/images/*.png"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/styles/*"
"${CMAKE_CURRENT_SOURCE_DIR}/conf.py"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/about.txt"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/about.txt"
"${CMAKE_CURRENT_SOURCE_DIR}/data/init/*init"
)
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}
"${CMAKE_CURRENT_SOURCE_DIR}/LICENSE.rst"
set(SPHINX_DEPS ${SPHINX_GLOB_DEPS} ${SPHINX_GLOB_RECURSE_DEPS} ${SPHINX_SCRIPT_DEPS}
"${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"
-j 2
-w "${CMAKE_BINARY_DIR}/docs/html/_sphinx-warnings.txt"
-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()