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.
develop
PeridexisErrant 2015-10-23 12:34:54 +11:00
parent a305c40bb2
commit a4708d07a1
7 changed files with 66 additions and 54 deletions

@ -184,10 +184,7 @@ endif()
# build the lib itself # build the lib itself
IF(BUILD_LIBRARY) IF(BUILD_LIBRARY)
add_subdirectory (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() endif()
install(DIRECTORY dfhack-config/ DESTINATION dfhack-config/default) install(DIRECTORY dfhack-config/ DESTINATION dfhack-config/default)
@ -204,21 +201,21 @@ 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 "alabaster")
set(SPHINX_THEME_DIR) set(SPHINX_THEME_DIR)
set(SPHINX_BINARY_BUILD_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build") set(SPHINX_BINARY_BUILD_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build")
set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build/_doctrees") set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build/_doctrees")
set(SPHINX_HTML_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/") set(SPHINX_HTML_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/")
configure_file( 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) @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/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" "${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"
"${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(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}" -c "${SPHINX_BINARY_BUILD_DIR}/docs"
-d "${SPHINX_CACHE_DIR}" -d "${SPHINX_CACHE_DIR}"
"${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}"
"${SPHINX_HTML_DIR}" "${SPHINX_HTML_DIR}"

@ -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 License of DFHack
================= =================
https://github.com/peterix/dfhack https://github.com/peterix/dfhack

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

@ -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. DFHack consists of variously licensed code, but invariably weak copyleft.
The main license is zlib/libpng, some bits are MIT licensed, and some are 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 Feel free to add your own extensions and plugins. Contributing back to
the DFHack repository is welcome and the right thing to do :) 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 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), 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 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 this section as a guide rather than iron law, match the surrounding text, and you'll

@ -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

@ -21,9 +21,11 @@ import sys
from os import listdir from os import listdir
from os.path import isfile, join, isdir, relpath from os.path import isfile, join, isdir, relpath
#import sys
currentDir = '@CMAKE_CURRENT_SOURCE_DIR@' currentDir = '@CMAKE_CURRENT_SOURCE_DIR@'
if currentDir.startswith('@'):
# Not running in CMake
currentDir = '.'
def makeIncludeAll(directory, extension): def makeIncludeAll(directory, extension):
outputFile = join(directory,'include-all.rst') 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 # |version| and |release|, also used in various other places throughout the
# built documents. # 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. # The short X.Y version.
version = '@DFHACK_VERSION@' version = '@DFHACK_VERSION@'
# The full version, including alpha/beta/rc tags. # The full version, including alpha/beta/rc tags.
release = '@DFHACK_VERSION@' 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 # The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages. # 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 # The reST default role (used for this markup: `text`) to use for all
# documents. # documents.
default_role = 'any' default_role = 'ref'
# If true, '()' will be appended to :func: etc. cross-reference text. # If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True #add_function_parentheses = True
@ -134,16 +143,9 @@ default_role = 'any'
# unit titles (such as .. function::). # unit titles (such as .. function::).
#add_module_names = True #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. # The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx' 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. # If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False #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 # The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes. # 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 # 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 # further. For a list of options available for each theme, see the
# documentation. # 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. # Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = [] #html_theme_path = []
@ -170,7 +178,7 @@ html_theme = '@SPHINX_THEME@'
#html_title = None #html_title = None
# A shorter title for the navigation bar. Default is the same as html_title. # 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 # The name of an image file (relative to this directory) to place at the top
# of the sidebar. # 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 # 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 # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large. # 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, # 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, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # 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 # Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied # .htaccess) here, relative to this directory. These files are copied
@ -200,17 +208,24 @@ html_static_path = []
#html_use_smartypants = True #html_use_smartypants = True
# Custom sidebar templates, maps document names to template names. # 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 # Additional templates that should be rendered to pages, maps page names to
# template names. # template names.
#html_additional_pages = {} #html_additional_pages = {}
# If false, no module index is generated. # If false, no module index is generated.
#html_domain_indices = True html_domain_indices = False
# If false, no index is generated. # 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. # If true, the index is split into individual pages for each letter.
#html_split_index = False #html_split_index = False
@ -238,10 +253,6 @@ html_static_path = []
# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' # 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
#html_search_language = 'en' #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 # The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used. # implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js' #html_search_scorer = 'scorer.js'

Before

Width:  |  Height:  |  Size: 2.4 KiB

After

Width:  |  Height:  |  Size: 2.4 KiB