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.

CMakeLists.txt

@@ -201,43 +201,30 @@ if (BUILD_DOCS)
   if (NOT SPHINX_FOUND)
     message(SEND_ERROR "Sphinx not found but BUILD_DOCS enabled")
   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
     "${CMAKE_CURRENT_SOURCE_DIR}/docs/*.rst"
     "${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}/scripts/*.lua"
-    "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*.lua"
-    "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*.lua"
-    "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*.lua"
-    "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*.lua"
-    "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*.lua"
-    "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*.lua"
-    "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*.lua"
-    "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*/*.lua"
-    "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*/*/*.lua"
+    "${CMAKE_CURRENT_SOURCE_DIR}/scripts/about.txt"
+    "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/about.txt"
+  )
+  file(GLOB_RECURSE SPHINX_SCRIPT_DEPS scripts "${CMAKE_CURRENT_SOURCE_DIR}"
+    "*.lua"
+    "*.rb"
   )
-  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_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE)
   add_custom_command(OUTPUT ${SPHINX_OUTPUT}
     COMMAND ${SPHINX_EXECUTABLE}
       -a -E -q -b html
-      -c "${SPHINX_BINARY_BUILD_DIR}/docs"
-      -d "${SPHINX_CACHE_DIR}"
+      -c "${CMAKE_CURRENT_SOURCE_DIR}/docs"
       "${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}
     COMMENT "Building HTML documentation with Sphinx"
   )
@@ -250,12 +237,10 @@ if (BUILD_DOCS)
   add_custom_command(TARGET dfhack_docs POST_BUILD
     COMMAND ${CMAKE_COMMAND} -E touch ${SPHINX_OUTPUT})
 
-  install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/html
+  install(DIRECTORY ${dfhack_SOURCE_DIR}/docs
       DESTINATION ${DFHACK_USERDOC_DESTINATION}
-      #FILES_MATCHING PATTERN "*.lua"
-      #               PATTERN "*.rb"
-      #               PATTERN "3rdparty" EXCLUDE
       )
+  install(FILES "README.html" DESTINATION "${DFHACK_DATA_DESTINATION}")
 endif()
 
 # Packaging with CPack!

NEWS.rst

@@ -29,9 +29,11 @@ Changelog
 
 DFHack Future
 =============
+
+Internals
+=========
 ::
 
-    Internals
         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
         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
         Plugin system is no longer restricted to plugins that exist on startup
         dfhack.init file locations significantly generalized
-    Lua
+
+Lua
+===
+::
+
         Scripts can be enabled with the built-in enable/disable commands
         A new function, reqscript(), is available as a safer alternative to script_environment()
         Lua viewscreens can choose not to intercept the OPTIONS keybinding
-    New internal commands
+
+New internal commands
+=====================
+::
+
         kill-lua: Interrupt running Lua scripts
         type: Show where a command is implemented
-    New plugins
+
+New plugins
+===========
+::
+
         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)
         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)
         fix-ster:  changes fertility/sterility of animals or dwarves
         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
           - pref-adjust: Adjust all preferences of all dwarves in play
           - 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
         kitchen-keys: Fixes DF kitchen meal keybindings
         kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences
         kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs
-    Fixes
+
+Fixes
+=====
+::
+
         Plugins with vmethod hooks can now be reloaded on OS X
         Lua's os.system() now works on OS X
         Fixed default arguments in Lua gametype detection functions
@@ -103,13 +129,18 @@ DFHack Future
         workflow: Fixed some issues with stuck jobs
           - Note: Existing stuck jobs must be cancelled and re-added
         zone: Fixed a crash when using "zone set" (and a few other potential crashes)
-    Misc Improvements
+
+Misc Improvements
+=================
+::
+
         DFHack documentation:
           - massively reorganised, into files of more readable size
           - added many missing entries
           - indexes, internal links, offline search all documents
           - includes documentation of linked projects (df-structures, 3rdparty scripts)
           - better HTML generation with Sphinx
+          - documentation for scripts now located in source files
         autolabor:
           - Stopped modification of labors that shouldn't be modified for brokers/diplomats
           - 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
           - farm-plot-select: Fixed issues with selecting undiscovered crops
         workflow: Improved handling of plant reactions
-    Removed
-        embark-tools nano: 1x1 embarks are now possible in vanilla 0.40.24
+
+Removed
+=======
+- `embark-tools` nano: 1x1 embarks are now possible in vanilla 0.40.24
 
 DFHack 0.40.24-r3
 =================

docs/conf.py

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