Commit 3a24ebc2 authored by David Thompson's avatar David Thompson

Add documentation skeleton back in.

parent af60450d
......@@ -18,4 +18,5 @@
[attr]lfs filter=lfs diff=lfs merge=lfs -text
data/** lfs
data/** lfs
doc/userguide/figures/** lfs
python:
version: 2.7
requirements_file: Documentation/requirements/dev.txt
requirements_file: doc/requirements/dev.txt
#ifndef __cmb_common_Version_h
#define __cmb_common_Version_h
/*! \file
* Both preprocessor macros and functions are available so
* that access is available at compile time and at run
* time, even from within wrapped languages like Python.
*/
/// Version number as a string.
#define CMB_VERSION "@cmb_version@"
/// Integer-valued major version number
#define CMB_VERSION_MAJOR @cmb_version_major@
/// Integer-valued minor version number
#define CMB_VERSION_MINOR @cmb_version_minor@
/// Integer-valued patch version number
#define CMB_VERSION_PATCH @cmb_version_patch@
#endif // __cmb_common_Version_h
####### MTK Documentation
## Reference Documentation
#
# If we have doxygen, create reference API documentation for CMB.
#
# This may one day generate documentation for third-party libraries
# (e.g., SMTK) which are referenced by CMB's documentation.
#
if(DOXYGEN_FOUND)
file(MAKE_DIRECTORY "${cmb_BINARY_DIR}/doc/reference")
configure_file(
${CMAKE_CURRENT_SOURCE_DIR}/cmb.doxyfile.in
${CMAKE_CURRENT_BINARY_DIR}/cmb.doxyfile
@ONLY
)
add_custom_command(
OUTPUT ${cmb_BINARY_DIR}/doc/reference/cmb.tags
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/cmb.doxyfile
WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/reference"
DEPENDS
"${CMAKE_CURRENT_BINARY_DIR}/cmb.doxyfile"
COMMENT "Generating CMB API documentation with Doxygen" VERBATIM
)
add_custom_target(doc
DEPENDS ${cmb_BINARY_DIR}/doc/reference/cmb.tags
)
endif(DOXYGEN_FOUND)
## End-user Documentation
#
# If we have rst2html, create the user's guide for CMB
# as an HTML document.
# Define a macro for processing reStructuredText files
# if docutils were found.
if (SPHINX_FOUND)
function(smtk_add_doc sphinxTargetName)
set(options)
set(oneValueArgs DESTINATION SOURCE_DIR BUILD_DIR)
set(multiValueArgs DEPENDS FIGURES)
cmake_parse_arguments(sphinx "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} )
if (NOT sphinx_SOURCE_DIR)
set(sphinx_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}") # Reasonable default
endif()
if (NOT sphinx_BUILD_DIR)
set(sphinx_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}") # Reasonable default
endif()
# Generate HTML version of docs
set(sphinx_HTML_TOP "${CMAKE_CURRENT_BINARY_DIR}/${sphinx_BUILD_DIR}/html/index.html")
add_custom_command(
OUTPUT "${sphinx_HTML_TOP}"
DEPENDS
${CMAKE_CURRENT_SOURCE_DIR}/conf.py
${sphinx_DEPENDS}
${figureList}
COMMAND ${SPHINX_EXECUTABLE}
ARGS
-b html
"${sphinx_SOURCE_DIR}"
"${sphinx_BUILD_DIR}/html"
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating HTML for ${sphinxTargetName}"
)
add_custom_target(doc-${sphinxTargetName} DEPENDS "${sphinx_HTML_TOP}")
if (sphinx_DESTINATION)
install(
DIRECTORY "${sphinx_BUILD_DIR}/html/"
DESTINATION "${sphinx_DESTINATION}"
COMPONENT Development)
install(
FILES ${figureList}
DESTINATION "${sphinx_DESTINATION}/figures"
COMPONENT Development)
endif()
endfunction()
set(CMB_USERGUIDE_DOCS
index.rst
userguide/index.rst
)
if (DOXYGEN_FOUND)
# Need doxygen docs built if possible
list(APPEND CMB_USERGUIDE_DOCS
${cmb_BINARY_DIR}/doc/reference/cmb.tags)
endif()
set(CMB_USERGUIDE_FIGS
)
# Add the top-level reStructuredText file.
# All others are included by it.
smtk_add_doc(userguide
DEPENDS ${CMB_USERGUIDE_DOCS}
#FIGURES ${CMB_USERGUIDE_FIGS}
BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/user
DESTINATION share/doc/cmb/userguide
)
endif()
This diff is collapsed.
This diff is collapsed.
"""
The findfigure Sphinx extension allows projects to
specify a set of search paths that images may appear in.
It is configured by two variables you can set in your
project's conf.py file:
findfigure_paths is a dictionary mapping builder
names to a tuple of paths to search.
findfigure_types is a dictionary mapping builder
names to a tuple of figure filename extensions,
in descending order of preference.
See setup() below for more information.
"""
import os
import sys
from docutils import nodes, utils
from docutils.parsers.rst import directives, states
from docutils.parsers.rst.directives.images import Image, Figure
import sphinx.builders
rememberedApp = None
class FindImageDirective(Image):
"""A directive that finds images in a search path."""
def run(self):
"""Process a new image."""
env = self.state.document.settings.env
reference = directives.uri(self.arguments[0])
if not os.path.isabs(reference):
# A relative path means we should search for the image
# Find the builder-specific path-list to search:
bname = rememberedApp.builder.format if rememberedApp != None else env.app.builder.name
if bname in env.app.config.findfigure_paths:
searchdirs = env.app.config.findfigure_paths[bname]
elif '*' in env.app.config.findfigure_paths:
searchdirs = env.app.config.findfigure_paths['*']
else:
searchdirs = (os.path.abspath('.'),)
if reference.endswith('.*'):
# Find the builder-specific list of extensions to try
base, dummy = os.path.splitext(reference)
if bname in env.app.config.findfigure_types:
searchexts = env.app.config.findfigure_types[bname]
elif '*' in env.app.config.findfigure_types:
searchexts = env.app.config.findfigure_types['*']
else:
searchexts = (
'.svg', '.pdf', '.png', '.jpeg', '.jpg', '.tiff', '.tif', '.gif')
else:
base = reference
searchexts = ('',)
# Now try finding the figure.
foundit = False
aref = base
for ext in searchexts:
for path in searchdirs:
try:
aref = os.path.join(path, base) + ext
# print ' TRY <%s>' % aref
status = os.stat(aref) # Could check status bits here.
foundit = True
break
except:
foundit = False
if foundit:
break
if not foundit:
# print 'MISSING FILE %s' % reference
return []
# print 'RESOLVED %s to %s' % (reference, aref)
rewr = os.path.relpath(
aref, os.path.join(env.srcdir, os.path.dirname(env.docname)))
# NB: We must rewrite path relative to source directory
# because otherwise the output stage will be unable
# to find it.
# print 'REWROTE %s to %s' % (aref, rewr)
self.arguments[0] = rewr
return Image.run(self)
class FindFigureDirective(Figure):
"""A directive that finds figure images in a search path."""
def run(self):
"""Process a new figure."""
env = self.state.document.settings.env
reference = directives.uri(self.arguments[0])
if not os.path.isabs(reference):
# A relative path means we should search for the image
# Find the builder-specific path-list to search:
bname = rememberedApp.builder.format if rememberedApp != None else env.app.builder.name
if bname in env.app.config.findfigure_paths:
searchdirs = env.app.config.findfigure_paths[bname]
elif '*' in env.app.config.findfigure_paths:
searchdirs = env.app.config.findfigure_paths['*']
else:
searchdirs = (os.path.abspath('.'),)
if reference.endswith('.*'):
# Find the builder-specific list of extensions to try
base, dummy = os.path.splitext(reference)
if bname in env.app.config.findfigure_types:
searchexts = env.app.config.findfigure_types[bname]
elif '*' in env.app.config.findfigure_types:
searchexts = env.app.config.findfigure_types['*']
else:
searchexts = (
'.svg', '.pdf', '.png', '.jpeg', '.jpg', '.tiff', '.tif', '.gif')
else:
base = reference
searchexts = ('',)
# Now try finding the figure.
foundit = False
aref = base
for ext in searchexts:
for path in searchdirs:
try:
aref = os.path.join(path, base) + ext
# print ' TRY <%s>' % aref
status = os.stat(aref) # Could check status bits here.
foundit = True
break
except:
foundit = False
if foundit:
break
if not foundit:
# print 'MISSING FILE %s' % reference
return []
# print 'RESOLVED %s to %s' % (reference, aref)
rewr = os.path.relpath(
aref, os.path.join(env.srcdir, os.path.dirname(env.docname)))
# NB: We must rewrite path relative to source directory
# because otherwise the output stage will be unable
# to find it.
# print 'REWROTE %s to %s rel %s' % (aref, rewr,
# os.path.abspath(os.path.dirname(env.docname)))
self.arguments[0] = rewr
return Figure.run(self)
def setup(app):
"""Read configuration for the module.
This is mainly a list of paths to search and
a dictionary of file extension preferences
for each builder.
findfigure_paths is a dictionary mapping builder
names to a tuple of paths to search.
findfigure_types is a dictionary mapping builder
names to a tuple of figure filename extensions,
in descending order of preference.
Both settings above take the usual builder names
(e.g., "html", "epub") as well as the special
name "*", which is used as a fallback when the
builder specified is not in the dictionary.
Thus you may put figures for different builders into
different search paths or you may simply use different
files types for figures, but place them all in the same
search paths (by only providing search paths for "*").
By default the current directory is searched.
The default figure extensions are different
for each builder.
An example is
findfigure_paths = {
'*': (
'@CMAKE_CURRENT_SOURCE_DIR@',
'@CMAKE_CURRENT_BINARY_DIR@')
}
findfigure_types = {
'html': ('.svg','.png','.jpeg','.jpg', '.gif'),
'epub': ('.svg','.png','.jpeg','.jpg', '.gif'),
'latex':('.pdf','.png','.jpeg','.jpg')
}, 'env')
This example uses the same set of search paths for
all builders but has the HTML and epub builders prefer
SVG files over raster images while the LaTeX builder
prefers PDF figures over raster images.
"""
defaultpath = os.path.abspath('.')
app.add_config_value('findfigure_paths',
{
'*': (defaultpath,)
}, 'env')
app.add_config_value('findfigure_types',
{
'html': ('.svg', '.png', '.jpeg', '.jpg', '.tiff', '.tif', '.gif'),
'epub': ('.svg', '.png', '.jpeg', '.jpg', '.tiff', '.tif', '.gif'),
'latex': ('.pdf', '.png', '.jpeg', '.jpg', '.tiff', '.tif')
}, 'env')
app.add_directive('findimage', FindImageDirective)
app.add_directive('findfigure', FindFigureDirective)
rememberedApp = app
################################
CMB: Computational Model Builder
################################
Version: |release|
.. highlight:: c++
.. role:: cxx(code)
:language: c++
.. findimage:: cmb-logo.*
Contents:
.. toctree::
:maxdepth: 4
userguide/index.rst
##################
Indices and tables
##################
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
pyparsing==1.5.7
Pygments==2.2.0
Sphinx==1.6.3
actdiag==0.5.4
blockdiag==1.5.3
sphinxcontrib-actdiag==0.7.2
sphinxcontrib-doxylink==1.3.0
sphinx_rtd_theme==0.2.4
breathe==4.6.0
================
CMB User's Guide
================
Computational Model Builder -- model builder or CMB for short --
is a customizable application to help you
(1) describe a simulation's input deck in enough detail that it can
be passed to a solver and
(2) create input files for a variety of solvers in different simulation
packages using your description.
This process can involve any or all of the following:
- importing a geometric model of the simulation domain or the domain's boundary;
- assigning sizing functions to specify mesh element size for analysis;
- submitting portions of the simulation domain to be meshed for analysis;
- assigning material properties to regions of the simulation domain;
- assigning boundary conditions to portions of the simulation domain's boundary;
- assigning initial conditions to portions of the simulation domain or its boundary; and
- assigning global simulation properties such as convergence criteria.
In order to do this, model builder needs a description of your simulation solver.
The description is a template which describes the simulation in a JSON or XML document,
plus a Python script that examines how the template has been filled out and writes
an input file for your simulation.
You can provide the template using the editor application that comes with CMB.
Once you have the template completed, you can use modelbuilder to fill out the
template, associate it with a mesh, and submit it to run.
.. toctree::
:maxdepth: 4
......@@ -150,6 +150,9 @@ build_paraview_client(modelbuilder
INSTALL_LIBRARY_DIR "${VTK_INSTALL_LIBRARY_DIR}"
INSTALL_ARCHIVE_DIR "${VTK_INSTALL_ARCHIVE_DIR}"
OPTIONAL_PLUGINS "${modelbuilder_plugins}"
# Disable this until we have a preference to prevent it,
# otherwise it interferes with debugging:
# SPLASH_IMAGE "${CMAKE_CURRENT_SOURCE_DIR}/resource/splash.png"
)
target_link_libraries(modelbuilder
......
Markdown is supported
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