Build docs in place; copy inputs so users can build

Building the docs now works the same way, no matter when it happens - in
a cloned repo or distributed version.

This means all the relative links keep working; and that users or
downstream distributors can rebuild the docs with extra scripts or .rst
files in place.

Finally, it eliminates a large number of potential bugs which only occur
in one build environment and are difficult to reproduce.

Also add headings and this work to future news.
develop
PeridexisErrant 2015-10-24 22:19:52 +11:00
parent 69090e114c
commit a3803d340e
3 changed files with 59 additions and 47 deletions

@ -201,43 +201,30 @@ if (BUILD_DOCS)
if (NOT SPHINX_FOUND) if (NOT SPHINX_FOUND)
message(SEND_ERROR "Sphinx not found but BUILD_DOCS enabled") message(SEND_ERROR "Sphinx not found but BUILD_DOCS enabled")
endif() endif()
set(SPHINX_THEME_DIR)
set(SPHINX_BINARY_BUILD_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build")
set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build/_doctrees")
set(SPHINX_HTML_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/")
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py"
"${SPHINX_BINARY_BUILD_DIR}/docs/conf.py"
@ONLY)
file(GLOB SPHINX_DEPS file(GLOB SPHINX_DEPS
"${CMAKE_CURRENT_SOURCE_DIR}/docs/*.rst" "${CMAKE_CURRENT_SOURCE_DIR}/docs/*.rst"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/images/*.png" "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/*.png"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/styles*" "${CMAKE_CURRENT_SOURCE_DIR}/docs/styles/*"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py" "${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/about.txt"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*.lua" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/about.txt"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*.lua" )
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*.lua" file(GLOB_RECURSE SPHINX_SCRIPT_DEPS scripts "${CMAKE_CURRENT_SOURCE_DIR}"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*.lua" "*.lua"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*.lua" "*.rb"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*.lua"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*.lua"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*/*.lua"
"${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*/*/*.lua"
) )
set(SPHINX_DEPS ${SPHINX_DEPS} LICENSE.rst NEWS.rst README.rst) set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst README.rst)
set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo") set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo")
set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE) set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE)
add_custom_command(OUTPUT ${SPHINX_OUTPUT} add_custom_command(OUTPUT ${SPHINX_OUTPUT}
COMMAND ${SPHINX_EXECUTABLE} COMMAND ${SPHINX_EXECUTABLE}
-a -E -q -b html -a -E -q -b html
-c "${SPHINX_BINARY_BUILD_DIR}/docs" -c "${CMAKE_CURRENT_SOURCE_DIR}/docs"
-d "${SPHINX_CACHE_DIR}"
"${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}"
"${SPHINX_HTML_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/html"
-w "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build/sphinx-warnings.txt"
DEPENDS ${SPHINX_DEPS} DEPENDS ${SPHINX_DEPS}
COMMENT "Building HTML documentation with Sphinx" COMMENT "Building HTML documentation with Sphinx"
) )
@ -250,12 +237,10 @@ if (BUILD_DOCS)
add_custom_command(TARGET dfhack_docs POST_BUILD add_custom_command(TARGET dfhack_docs POST_BUILD
COMMAND ${CMAKE_COMMAND} -E touch ${SPHINX_OUTPUT}) COMMAND ${CMAKE_COMMAND} -E touch ${SPHINX_OUTPUT})
install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/html install(DIRECTORY ${dfhack_SOURCE_DIR}/docs
DESTINATION ${DFHACK_USERDOC_DESTINATION} DESTINATION ${DFHACK_USERDOC_DESTINATION}
#FILES_MATCHING PATTERN "*.lua"
# PATTERN "*.rb"
# PATTERN "3rdparty" EXCLUDE
) )
install(FILES "README.html" DESTINATION "${DFHACK_DATA_DESTINATION}")
endif() endif()
# Packaging with CPack! # Packaging with CPack!

@ -29,9 +29,11 @@ Changelog
DFHack Future DFHack Future
============= =============
::
Internals Internals
=========
::
A method for caching screen output is now available to Lua (and C++) A method for caching screen output is now available to Lua (and C++)
Developer plugins can be ignored on startup by setting the DFHACK_NO_DEV_PLUGINS environment variable Developer plugins can be ignored on startup by setting the DFHACK_NO_DEV_PLUGINS environment variable
The console on Linux and OS X now recognizes keyboard input between prompts The console on Linux and OS X now recognizes keyboard input between prompts
@ -44,18 +46,34 @@ DFHack Future
Keybindings can now use F10-F12 and 0-9 Keybindings can now use F10-F12 and 0-9
Plugin system is no longer restricted to plugins that exist on startup Plugin system is no longer restricted to plugins that exist on startup
dfhack.init file locations significantly generalized dfhack.init file locations significantly generalized
Lua Lua
===
::
Scripts can be enabled with the built-in enable/disable commands Scripts can be enabled with the built-in enable/disable commands
A new function, reqscript(), is available as a safer alternative to script_environment() A new function, reqscript(), is available as a safer alternative to script_environment()
Lua viewscreens can choose not to intercept the OPTIONS keybinding Lua viewscreens can choose not to intercept the OPTIONS keybinding
New internal commands New internal commands
=====================
::
kill-lua: Interrupt running Lua scripts kill-lua: Interrupt running Lua scripts
type: Show where a command is implemented type: Show where a command is implemented
New plugins New plugins
===========
::
confirm: Adds confirmation dialogs for several potentially dangerous actions confirm: Adds confirmation dialogs for several potentially dangerous actions
fix-unit-occupancy: Fixes issues with unit occupancy, such as faulty "unit blocking tile" messages (bug 3499) fix-unit-occupancy: Fixes issues with unit occupancy, such as faulty "unit blocking tile" messages (bug 3499)
title-version (formerly vshook): Display DFHack version on title screen title-version (formerly vshook): Display DFHack version on title screen
New scripts New scripts
===========
::
burial: sets all unowned coffins to allow burial ("-pets" to allow pets too) burial: sets all unowned coffins to allow burial ("-pets" to allow pets too)
fix-ster: changes fertility/sterility of animals or dwarves fix-ster: changes fertility/sterility of animals or dwarves
view-item-info: adds information and customisable descriptions to item viewscreens view-item-info: adds information and customisable descriptions to item viewscreens
@ -71,12 +89,20 @@ DFHack Future
- make-legendary: modify skill(s) of a single unit - make-legendary: modify skill(s) of a single unit
- pref-adjust: Adjust all preferences of all dwarves in play - pref-adjust: Adjust all preferences of all dwarves in play
- rejuvenate: make any "old" dwarf 20 years old - rejuvenate: make any "old" dwarf 20 years old
New tweaks New tweaks
==========
::
embark-profile-name: Allows the use of lowercase letters when saving embark profiles embark-profile-name: Allows the use of lowercase letters when saving embark profiles
kitchen-keys: Fixes DF kitchen meal keybindings kitchen-keys: Fixes DF kitchen meal keybindings
kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences
kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs
Fixes Fixes
=====
::
Plugins with vmethod hooks can now be reloaded on OS X Plugins with vmethod hooks can now be reloaded on OS X
Lua's os.system() now works on OS X Lua's os.system() now works on OS X
Fixed default arguments in Lua gametype detection functions Fixed default arguments in Lua gametype detection functions
@ -103,13 +129,18 @@ DFHack Future
workflow: Fixed some issues with stuck jobs workflow: Fixed some issues with stuck jobs
- Note: Existing stuck jobs must be cancelled and re-added - Note: Existing stuck jobs must be cancelled and re-added
zone: Fixed a crash when using "zone set" (and a few other potential crashes) zone: Fixed a crash when using "zone set" (and a few other potential crashes)
Misc Improvements Misc Improvements
=================
::
DFHack documentation: DFHack documentation:
- massively reorganised, into files of more readable size - massively reorganised, into files of more readable size
- added many missing entries - added many missing entries
- indexes, internal links, offline search all documents - indexes, internal links, offline search all documents
- includes documentation of linked projects (df-structures, 3rdparty scripts) - includes documentation of linked projects (df-structures, 3rdparty scripts)
- better HTML generation with Sphinx - better HTML generation with Sphinx
- documentation for scripts now located in source files
autolabor: autolabor:
- Stopped modification of labors that shouldn't be modified for brokers/diplomats - Stopped modification of labors that shouldn't be modified for brokers/diplomats
- Prioritize skilled dwarves more efficiently - Prioritize skilled dwarves more efficiently
@ -149,8 +180,10 @@ DFHack Future
- debug output now logged to stderr.log instead of console - makes DFHack start faster - debug output now logged to stderr.log instead of console - makes DFHack start faster
- farm-plot-select: Fixed issues with selecting undiscovered crops - farm-plot-select: Fixed issues with selecting undiscovered crops
workflow: Improved handling of plant reactions workflow: Improved handling of plant reactions
Removed Removed
embark-tools nano: 1x1 embarks are now possible in vanilla 0.40.24 =======
- `embark-tools` nano: 1x1 embarks are now possible in vanilla 0.40.24
DFHack 0.40.24-r3 DFHack 0.40.24-r3
================= =================

@ -141,7 +141,7 @@ author = 'The DFHack Team'
# |version| and |release|, also used in various other places throughout the # |version| and |release|, also used in various other places throughout the
# built documents. # built documents.
def get_version(default): def get_version():
"""Return the DFHack version string, from CMakeLists.txt""" """Return the DFHack version string, from CMakeLists.txt"""
version = release = '' version = release = ''
try: try:
@ -153,20 +153,14 @@ def get_version(default):
release = s.upper().replace('SET(DFHACK_RELEASE "', '').lower() release = s.upper().replace('SET(DFHACK_RELEASE "', '').lower()
return (version + '-' + release).replace('")\n', '') return (version + '-' + release).replace('")\n', '')
except IOError: except IOError:
return default return 'unknown'
# The short X.Y version. # The short X.Y version.
version = '@DFHACK_VERSION@'
# The full version, including alpha/beta/rc tags. # The full version, including alpha/beta/rc tags.
release = '@DFHACK_VERSION@' version = release = get_version()
if version == '@DFHACK_VERSION@':
# Not running through CMake...
version = release = get_version('@DFHACK_VERSION@')
# The language for content autogenerated by Sphinx. Refer to documentation # The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages. # for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs. # This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases. # Usually you set "language" from the command line for these cases.
language = None language = None