Allow Sphinx-doc to work with or without cmake

This mainly involved tweaking a few filenames and configuration paths to
allow consistency in all scenarios.  It cleared up a few errors in the
process too!

I also clarified the placement of the LICENSE file, and finished
configuring the Alabaster style.  This required moving some stuff out of
the CMake system to conf.py to avoid later breakage.

CMakeLists.txt

@@ -184,10 +184,7 @@ endif()
 # build the lib itself
 IF(BUILD_LIBRARY)
     add_subdirectory (library)
-    ## install the default documentation files
+    install(FILES LICENSE.rst NEWS.rst DESTINATION ${DFHACK_USERDOC_DESTINATION})
-    #install(FILES LICENSE NEWS "Lua API.html" Readme.html Compile.html Contributors.html DESTINATION ${DFHACK_USERDOC_DESTINATION})
-    install(FILES LICENSE NEWS DESTINATION ${DFHACK_USERDOC_DESTINATION})
-    #install(DIRECTORY docs/images DESTINATION ${DFHACK_USERDOC_DESTINATION})
 endif()
 
 install(DIRECTORY dfhack-config/ DESTINATION dfhack-config/default)
@@ -204,21 +201,21 @@ if (BUILD_DOCS)
   if (NOT SPHINX_FOUND)
     message(SEND_ERROR "Sphinx not found but BUILD_DOCS enabled")
   endif()
-  set(SPHINX_THEME "alabaster")
   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.in"
+    "${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py"
-    "${SPHINX_BINARY_BUILD_DIR}/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/conf.py.in"
+    "${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"
@@ -230,14 +227,14 @@ if (BUILD_DOCS)
     "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*/*.lua"
     "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*/*/*.lua"
   )
-  set(SPHINX_DEPS ${SPHINX_DEPS} LICENSE NEWS README.rst)
+  set(SPHINX_DEPS ${SPHINX_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}"
+      -c "${SPHINX_BINARY_BUILD_DIR}/docs"
       -d "${SPHINX_CACHE_DIR}"
       "${CMAKE_CURRENT_SOURCE_DIR}"
       "${SPHINX_HTML_DIR}"

LICENSE.rst

@@ -1,3 +1,13 @@
+.. _license:
+
+########
+Licenses
+########
+
+DFHack is distributed under a range of permissive and weakly copyleft licenses.
+
+The core uses the ZLib license; the others are described below.
+
 License of DFHack
 =================
 https://github.com/peterix/dfhack

README.rst

@@ -44,7 +44,7 @@ Other Contents:
    :maxdepth: 1
 
    docs/Authors
-   docs/Licenses
+   LICENSE
    NEWS
 
 For Developers:

docs/Contributing.rst

@@ -83,7 +83,7 @@ documentation is built with Sphinx, which runs automatically at compile time.
 
 DFHack consists of variously licensed code, but invariably weak copyleft.
 The main license is zlib/libpng, some bits are MIT licensed, and some are
-BSD licensed.  See the ``LICENSE`` document for more information.
+BSD licensed.  See the `license` for more information.
 
 Feel free to add your own extensions and plugins. Contributing back to
 the DFHack repository is welcome and the right thing to do :)
@@ -118,6 +118,11 @@ comprehensive interface for visualisers such as Armok Vision.
 
 Documentation Standards
 =======================
+DFHack documentation is built with Sphinx, and configured automatically
+through CMake.  If you want to build the docs *only*, use this command::
+
+    sphinx-build -a -c docs . docs/html
+
 Whether you're adding new code or just fixing old documentation (and there's plenty),
 there are a few important standards for completeness and consistent style.  Treat
 this section as a guide rather than iron law, match the surrounding text, and you'll

docs/Licenses.rst

@@ -1,11 +0,0 @@
-.. _license:
-
-########
-Licenses
-########
-
-DFHack is distributed under a range of permissive and weakly copyleft licenses.
-
-The core uses the ZLib license; the others are described below.
-
-.. include:: ../LICENSE

docs/conf.py

@@ -21,9 +21,11 @@ import sys
 
 from os import listdir
 from os.path import isfile, join, isdir, relpath
-#import sys
 
 currentDir = '@CMAKE_CURRENT_SOURCE_DIR@'
+if currentDir.startswith('@'):
+    # Not running in CMake
+    currentDir = '.'
 
 def makeIncludeAll(directory, extension):
   outputFile = join(directory,'include-all.rst')
@@ -90,22 +92,29 @@ author = 'The DFHack Team'
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 
-#def get_version():
+def get_version(default):
-#    """Return the DFHack version string, from CMakeLists.txt"""
+    """Return the DFHack version string, from CMakeLists.txt"""
-#    version, release = '', ''
+    version = release = ''
-#    with open('CMakeLists.txt') as f:
+    try:
-#        for s in f.readlines():
+        with open('../CMakeLists.txt') as f:
-#            if fnmatch.fnmatch(s.upper(), 'SET(DF_VERSION "?.??.??")\n'):
+            for s in f.readlines():
-#                version = s.upper().replace('SET(DF_VERSION "', '')
+                if fnmatch.fnmatch(s.upper(), 'SET(DF_VERSION "?.??.??")\n'):
-#            elif fnmatch.fnmatch(s.upper(), 'SET(DFHACK_RELEASE "r*")\n'):
+                    version = s.upper().replace('SET(DF_VERSION "', '')
-#                release = s.upper().replace('SET(DFHACK_RELEASE "', '').lower()
+                elif fnmatch.fnmatch(s.upper(), 'SET(DFHACK_RELEASE "r*")\n'):
-#    return (version + '-' + release).replace('")\n', '')
+                    release = s.upper().replace('SET(DFHACK_RELEASE "', '').lower()
+        return (version + '-' + release).replace('")\n', '')
+    except IOError:
+        return default
 
 # 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@')
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -125,7 +134,7 @@ exclude_patterns = ['docs/_build/*', 'depends/*']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
-default_role = 'any'
+default_role = 'ref'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
@@ -134,16 +143,9 @@ default_role = 'any'
 # unit titles (such as .. function::).
 #add_module_names = True
 
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
@@ -155,12 +157,18 @@ todo_include_todos = False
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = '@SPHINX_THEME@'
+html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    #'logo': 'logo.png',
+    'github_user': 'DFHack',
+    'github_repo': 'dfhack',
+    'github_button': False,
+    'travis_button': False,
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -170,7 +178,7 @@ html_theme = '@SPHINX_THEME@'
 #html_title = None
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
+html_short_title = 'DFHack Docs'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
@@ -179,12 +187,12 @@ html_theme = '@SPHINX_THEME@'
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = 'dfhack-icon.ico'
+html_favicon = 'styles/dfhack-icon.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path = ['styles']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -200,17 +208,24 @@ html_static_path = []
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+    '**': [
+        'about.html',
+        'localtoc.html',
+        'relations.html',
+        'searchbox.html',
+    ]
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 #html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_domain_indices = True
+html_domain_indices = False
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = False
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
@@ -238,10 +253,6 @@ html_static_path = []
 #   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
 #html_search_language = 'en'
 
-# A dictionary with options for the search language support, empty by default.
-# Now only 'ja' uses this config value
-#html_search_options = {'type': 'default'}
-
 # The name of a javascript file (relative to the configuration directory) that
 # implements a search results scorer. If empty, the default will be used.
 #html_search_scorer = 'scorer.js'