From a4708d07a18cc3380c5c65b91469d11c3d86dbaa Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 23 Oct 2015 12:34:54 +1100 Subject: [PATCH] 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 | 17 +++--- LICENSE => LICENSE.rst | 10 ++++ README.rst | 2 +- docs/Contributing.rst | 7 ++- docs/Licenses.rst | 11 ---- docs/{conf.py.in => conf.py} | 73 ++++++++++++++---------- docs/{images => styles}/dfhack-icon.ico | Bin 7 files changed, 66 insertions(+), 54 deletions(-) rename LICENSE => LICENSE.rst (98%) delete mode 100644 docs/Licenses.rst rename docs/{conf.py.in => conf.py} (88%) rename docs/{images => styles}/dfhack-icon.ico (100%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 84db3f36f..649580f9e 100644 --- a/CMakeLists.txt +++ b/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 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}) + install(FILES LICENSE.rst NEWS.rst 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" - "${SPHINX_BINARY_BUILD_DIR}/conf.py" + "${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/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}" diff --git a/LICENSE b/LICENSE.rst similarity index 98% rename from LICENSE rename to LICENSE.rst index 9bdc729f0..490b07a6e 100644 --- a/LICENSE +++ b/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 diff --git a/README.rst b/README.rst index 801b7c7f2..dcf3fb905 100644 --- a/README.rst +++ b/README.rst @@ -44,7 +44,7 @@ Other Contents: :maxdepth: 1 docs/Authors - docs/Licenses + LICENSE NEWS For Developers: diff --git a/docs/Contributing.rst b/docs/Contributing.rst index c374a4b95..867058e85 100644 --- a/docs/Contributing.rst +++ b/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 diff --git a/docs/Licenses.rst b/docs/Licenses.rst deleted file mode 100644 index c02227720..000000000 --- a/docs/Licenses.rst +++ /dev/null @@ -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 diff --git a/docs/conf.py.in b/docs/conf.py similarity index 88% rename from docs/conf.py.in rename to docs/conf.py index 15e4490b1..59fd656a8 100644 --- a/docs/conf.py.in +++ b/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(): -# """Return the DFHack version string, from CMakeLists.txt""" -# version, release = '', '' -# with open('CMakeLists.txt') as f: -# for s in f.readlines(): -# if fnmatch.fnmatch(s.upper(), 'SET(DF_VERSION "?.??.??")\n'): -# version = s.upper().replace('SET(DF_VERSION "', '') -# elif fnmatch.fnmatch(s.upper(), 'SET(DFHACK_RELEASE "r*")\n'): -# release = s.upper().replace('SET(DFHACK_RELEASE "', '').lower() -# return (version + '-' + release).replace('")\n', '') +def get_version(default): + """Return the DFHack version string, from CMakeLists.txt""" + version = release = '' + try: + with open('../CMakeLists.txt') as f: + for s in f.readlines(): + if fnmatch.fnmatch(s.upper(), 'SET(DF_VERSION "?.??.??")\n'): + version = s.upper().replace('SET(DF_VERSION "', '') + elif fnmatch.fnmatch(s.upper(), 'SET(DFHACK_RELEASE "r*")\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' diff --git a/docs/images/dfhack-icon.ico b/docs/styles/dfhack-icon.ico similarity index 100% rename from docs/images/dfhack-icon.ico rename to docs/styles/dfhack-icon.ico