Skip to content
Snippets Groups Projects
Commit 610fd857 authored by Ben Cumming's avatar Ben Cumming Committed by Sam Yates
Browse files

Basic Sphinx Documentation (#328)

Adds support for building documentation with Sphinx from reStructuredText-formatted files in the `doc` subdirectory. Automatic building has been verified with ReadTheDocs.

* Add basic documentation to the `doc` path.
* Use a git submodule and associated CMake to pull in ReadTheDocs theme at configuration time.
parent 12852eb4
No related branches found
No related tags found
No related merge requests found
Showing
with 367 additions and 5 deletions
[submodule "tests/ubench/google-benchmark"]
path = tests/ubench/google-benchmark
url = https://github.com/google/benchmark
[submodule "doc/rtd_theme"]
path = doc/rtd_theme
url = https://github.com/rtfd/sphinx_rtd_theme.git
NestMC prototype includes code from the open source community. Thank you!
Arbor includes code from the open source community. Thank you!
## JSON for Modern C++
......@@ -10,13 +10,22 @@ https://github.com/nlohmann/json
## Templatized C++ Command Line Parser Library (TCLAP)
A header only C++ library for command line argument parsing, written by Michael E. Smoot.
MIT license
MIT license.
https://sourceforge.net/projects/tclap
## TBB module for CMake
A CMake file for Intel Threading Building Blocks (TBB) written by Justus Calvin (GitHub handle justusc).
MIT license.
The CMake scripts provided in the Intel Threading Building Blocks respository are
to configure TBB. These are located in the cmake/tbb path.
Apache 2.0 license.
https://github.com/01org/tbb/blob/tbb_2017/LICENSE
## Sphinx module for CMake
The CMake script cmake/FindSphinx.cmake is a modified version of a script from the LLVM
project.
BSD License.
https://github.com/justusc/FindTBB
http://llvm.org/
......@@ -291,3 +291,4 @@ add_subdirectory(src)
add_subdirectory(tests)
add_subdirectory(miniapp)
add_subdirectory(lmorpho)
add_subdirectory(doc)
# based on a script from the llvm project:
# http://releases.llvm.org/4.0.0/LICENSE.TXT
# CMake find_package() Module for Sphinx documentation generator
# http://sphinx-doc.org/
#
# Example usage:
#
# find_package(Sphinx)
#
# If successful the following variables will be defined
# SPHINX_FOUND
# SPHINX_EXECUTABLE
find_program(
SPHINX_EXECUTABLE
NAMES sphinx-build sphinx-build2
DOC "Path to sphinx-build executable")
# this will also set SPHINX_FOUND to true if SPHINX_EXECUTABLE exists
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(
Sphinx
"Failed to locate sphinx-build executable"
SPHINX_EXECUTABLE)
# exclude working directories
build
static
# Set up rtd theme as an external project.
set(rtdtheme_src_dir "${CMAKE_CURRENT_SOURCE_DIR}/rtd_theme")
find_package(Git)
if(NOT EXISTS "${rtdtheme_src_dir}/.git")
set(git_failed)
if(GIT_FOUND)
message(STATUS "Updating the ReadTheDocs theme submodule ${rtdtheme_src_dir}")
execute_process(
COMMAND "${GIT_EXECUTABLE}" submodule update --init "${rtdtheme_src_dir}"
WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
ERROR_VARIABLE git_error
RESULT_VARIABLE git_result)
if(NOT git_result EQUAL 0)
set(git_failed "${git_error}")
endif()
else()
set(git_failed "git not found")
endif()
if(git_failed)
message(WARNING "Unable to update the ReadTheDocs theme submodule: ${git_failed}")
endif()
endif()
# a static path is required to avoid warning messages from sphinx-build
file(MAKE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/static")
# configure target for the sphinx-generated html docs
find_package(Sphinx)
set(DOCS_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/html")
set(DOCS_DOC_TREE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
set(DOCS_TARGET_NAME docs)
if (SPHINX_FOUND)
add_custom_target( ${DOCS_TARGET_NAME}
COMMAND
${SPHINX_EXECUTABLE}
-b html
-d "${DOCS_DOC_TREE_DIR}"
-q # Quiet: no output other than errors and warnings.
"${CMAKE_CURRENT_SOURCE_DIR}" # Source
"${DOCS_BUILD_DIR}" # Output
COMMENT
"Generating Sphinx documentation")
else()
add_custom_target( ${DOCS_TARGET_NAME}
COMMAND
echo "Error: Sphinx must be installed to build documentation."
COMMAND
exit 1 # return error code to let CMake know that the build proccess should fail
COMMENT
"Generating Sphinx documentation")
endif()
# remove generated documentation when make clean is run
set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${DOCS_BUILD_DIR}")
unset(git_failed)
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# Arbor documentation build configuration file, created by
# sphinx-quickstart on Wed Jul 26 18:29:23 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.todo',
'sphinx.ext.mathjax']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'Arbor'
copyright = '2017, ETHZ & FZ Julich'
author = 'ETHZ & FZ Julich'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.1'
# The full version, including alpha/beta/rc tags.
release = '0.1'
# 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
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['build', 'Thumbs.db', '.DS_Store', 'rtd_theme']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
# Use the ReadTheDocs theme
html_theme = "sphinx_rtd_theme"
html_theme_path = ["rtd_theme", ]
# html_theme_options = {}
# 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 = ['static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# This is required for the alabaster theme
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
#html_sidebars = {
# '**': [
# 'about.html',
# 'navigation.html',
# 'relations.html', # needs 'show_related': True theme option to display
# 'searchbox.html',
# 'donate.html',
# ]
#}
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'Arbordoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'Arbor.tex', 'Arbor Documentation',
'ETHZ \\& FZ Julich', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'arbor', 'Arbor Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'Arbor', 'Arbor Documentation',
author, 'Arbor', 'One line description of project.',
'Miscellaneous'),
]
Arbor
=====
Arbor is a high-performance library for computationa neurscience simulations.
.. toctree::
:maxdepth: 1
introduction
.. toctree::
:caption: Getting Stared:
:maxdepth: 1
install
.. toctree::
:caption: Users:
:maxdepth: 1
users
.. toctree::
:caption: Developers:
:maxdepth: 1
library
Installing
##############
Installation guide.
.. _install_requirements:
Before starting
===============
We will require:
* git
* cmake 3.0
* C++11 compliant compiler
For GPU support:
* NVIDIA CUDA toolkit 8.0
To make these docs you also need:
* Sphinx
.. _downloading:
Downloading
======================================
The easiest way to acquire the latest version of Arbor is to check the code out from our GitHub repository:
.. code-block:: bash
git clone https://github.com/eth-cscs/nestmc-proto.git
You can also point your browser to our `Github page <https://github.com/eth-cscs/nestmc-proto>`_ and download a zip file.
.. _install_desktop:
Basic Installation
======================================
Before building an optimzed version for your target system, it is a good idea to build a debug version:
.. code-block:: bash
# make a path for building
mkdir build
cd build
# configure and build
cmake ..
make -j 4
# run tests
./test/test.exe
./test/global_communication.exe
Why Arbor?
##########
The diverse ecosystem of emerging HPC computing architectures promises exciting opportunities for larger, more detailed simulations run over longer time periods.
Arbor is a library developed by the HPC community to help computational neuroscientists take advantage of such systems.
Library Reference
#################
Low level library reference material goes here, e.g. `range` library documentation.
File moved
File moved
File moved
File moved
File moved
File moved
File moved
File moved
File moved
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment