From a3803d340eed87ddf9f7eb05f5f702d0eafdce36 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 24 Oct 2015 22:19:52 +1100 Subject: [PATCH] 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 | 41 +++++++++++++------------------------- NEWS.rst | 53 ++++++++++++++++++++++++++++++++++++++++---------- docs/conf.py | 12 +++--------- 3 files changed, 59 insertions(+), 47 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 649580f9e..c5d343ee4 100644 --- a/CMakeLists.txt +++ b/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! diff --git a/NEWS.rst b/NEWS.rst index 304150e13..e0a6639e0 100644 --- a/NEWS.rst +++ b/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 ================= diff --git a/docs/conf.py b/docs/conf.py index e13fcda56..0f608e30e 100644 --- a/docs/conf.py +++ b/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