Commit dd8c55db authored by David Thompson's avatar David Thompson

Documentation enhancements.

parent 1b9f41c0
file(STRINGS version.txt version_string )
string(REGEX MATCH "([0-9]+)\\.([0-9]+)\\.([0-9]+)[-]*(.*)"
version_matches "${version_string}")
set(SMTK_VERSION_MAJOR ${CMAKE_MATCH_1})
set(SMTK_VERSION_MINOR ${CMAKE_MATCH_2})
set(SMTK_VERSION "${SMTK_VERSION_MAJOR}.${SMTK_VERSION_MINOR}")
if (CMAKE_MATCH_3)
set(SMTK_VERSION_PATCH ${CMAKE_MATCH_3})
set(SMTK_VERSION "${SMTK_VERSION}.${SMTK_VERSION_PATCH}")
else()
set(SMTK_VERSION_PATCH 0)
endif()
# To be thorough, we should split the label into "-prerelease+metadata"
# and, if prerelease is specified, use it in determining precedence
# according to semantic versioning rules at http://semver.org/ .
# For now, just make the information available as a label:
if (CMAKE_MATCH_4)
set(SMTK_VERSION_LABEL "${CMAKE_MATCH_4}")
endif()
......@@ -27,20 +27,15 @@ project(SMTK)
# to keep appending over multiple runs.
file(REMOVE ${PROJECT_BINARY_DIR}/SMTKTargets.cmake)
#Add our Cmake directory to the module search path
list(APPEND CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${SMTK_SOURCE_DIR}/CMake)
################################################################################
# SMTK version number
include(SMTKVersion)
set(SMTK_VERSION_MAJOR 1)
set(SMTK_VERSION_MINOR 1)
set(SMTK_VERSION_PATCH 0)
set(SMTK_VERSION
"${SMTK_VERSION_MAJOR}.${SMTK_VERSION_MINOR}.${SMTK_VERSION_PATCH}")
#
################################################################################
#Add our Cmake directory to the module search path
set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${SMTK_SOURCE_DIR}/CMake)
# Include GNU install directory module to detect where to install
# files on Linux/Unix systems (e.g., lib vs lib64)
include(GNUInstallDirs)
......
![CMB](doc/images/smtk_logo.png)
![SMTK](doc/images/smtk_logo.png)
Introduction
============
The [Simulation Model Toolkit (SMTK)][SMTK] is an open-source, multi-platform toolkit for supporting simulation workflows by providing access to different modeling kernels, mesh databases, and simulation infomation (via its attribute system). SMTK is developed as part of the [Computational Model Builder (CMB)][CMB] effort and provides extensions for [ParaView][],
The [Simulation Model Toolkit (SMTK)][SMTK] is an open-source, multi-platform toolkit for supporting simulation workflows by providing access to different modeling kernels, mesh databases, and simulation infomation (via its attribute system). SMTK is developed as part of the [Computational Model Builder (CMB)][CMB] effort and provides extensions for [ParaView][],
[Visualization Toolkit (VTK)][VTK] and [Qt][].
The project
......@@ -64,6 +64,6 @@ License
=======
CMB is distributed under the OSI-approved BSD 3-clause License.
See [License.txt][] for details.
See [License.txt][] for details.
[License.txt]: LICENSE.txt
......@@ -14,8 +14,11 @@
import sys
import os
import datetime
readTheDocs = os.environ.get('READTHEDOCS', None) != None
localReadTheDocs = os.environ.get('LOCALREADTHEDOCS', None) != None
localSkipDoxygen = os.environ.get('LOCALSKIPDOXYGEN', None) != None
sys.path.append(os.getcwd()) # So that the findfigure package can be imported
# FIXME: Is the penultimate argument always the source dir?
sourcedir = sys.argv[-2]
......@@ -74,7 +77,7 @@ def configFile(srcdir, blddir, templateFile, outputFile, keywords):
ofile.write(data)
ofile.close()
if readTheDocs:
if readTheDocs or localReadTheDocs:
"""Configure files and run Doxygen ourselves"""
# Configure some files
configFile(sourcedir, builddir, '../CMake/Version.h.in', '../smtk/common/Version.h', {
......@@ -83,10 +86,11 @@ if readTheDocs:
'@SMTK_VERSION_PATCH@': 0,
'@SMTK_VERSION@': '1.1.0'})
# Run doxygen ourselves on ReadTheDocs.org so that doxylinks will work.
runDoxygen(sourcedir, builddir, 'sparsehash.doxyfile.in',
'sparsehash.doxyfile')
runDoxygen(sourcedir, builddir, 'cjson.doxyfile.in', 'cjson.doxyfile')
runDoxygen(sourcedir, builddir, 'smtk.doxyfile.in', 'smtk.doxyfile')
if not localSkipDoxygen:
runDoxygen(sourcedir, builddir, 'sparsehash.doxyfile.in',
'sparsehash.doxyfile')
runDoxygen(sourcedir, builddir, 'cjson.doxyfile.in', 'cjson.doxyfile')
runDoxygen(sourcedir, builddir, 'smtk.doxyfile.in', 'smtk.doxyfile')
# 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
......@@ -127,16 +131,30 @@ master_doc = 'index'
# General information about the project.
project = u'SMTK'
copyright = u'2014, Kitware, Inc.'
year = datetime.datetime.now().year
copyright = u'%d, Kitware, Inc.' % year
# 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 = '1.0'
# The full version, including alpha/beta/rc tags.
release = '1.0'
def readVersionInfo(srcdir):
import re
pattern = re.compile('([0-9]+)\\.([0-9]+)(\\.([0-9]+)(-(.*))?)?')
vinfo = open(os.path.join(srcdir, '..', 'version.txt'), 'r').read().strip()
m = pattern.match(vinfo).groups()
major = int(m[0])
minor = int(m[1])
patch = int(m[3] or '0')
label = m[5]
# 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 = '%s.%s' % (major, minor)
# The full version, including alpha/beta/rc tags.
release = vinfo
return (version, release)
version, release = readVersionInfo(sourcedir)
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
......@@ -239,7 +257,7 @@ breathe_projects = {
'smtk': os.path.join(builddir, '..', '..', 'reference', 'smtk', 'xml') + os.path.sep,
}
breathe_default_project = 'smtk'
breathe_default_members = ['members', 'protected-members', 'undoc-members']
breathe_default_members = ('members', 'protected-members', 'undoc-members')
# -- Options for HTML output ----------------------------------------------
......
################################################
SMTK: Simulation Modeling Tool Kit Version 1.1.0
################################################
##################################
SMTK: Simulation Modeling Tool Kit
##################################
Version: |release|
.. highlight:: c++
......
......@@ -48,7 +48,18 @@ also accessible in Python, whose instances perform the following functions:
:smtk:`System <smtk::attribute::System>`
instances hold collections of attributes associated with a
particular purpose such as defining a simulation's input deck.
particular purpose such as
* defining a simulation's input deck (see the
`simulation workflows repository <https://gitlab.kitware.com/cmb/simulation-workflows>`_
for examples);
* specifying locations where input and output files are located
during the export process (SMTK's simulation subsystem creates
an attribute system for this purpose); and
* defining operations that can be performed on a geometric model
(SMTK's geometric modeling system uses an attribute system to
hold definitions for each modeling operation that can be
performed by each of its modeling kernels).
Because it can be tedious to programmatically create a bunch of
instances of the classes above to represent a particular simulation's
......@@ -56,10 +67,10 @@ input deck, SMTK provides an XML file format for serializing and
deserializing all of the attributes, definitions, items, and item-definitions
stored in an attribute system.
Components of the attribute system
Interfaces to the attribute system
----------------------------------
The attribute system has three main components:
The attribute system has three interfaces:
1. An XML file syntax for specifying the kinds data to be modeled
for individual simulation codes and problem domains.
......
.. _smtk-attribute-sys:
***********************
-----------------------
SMTK's Attribute System
***********************
-----------------------
General Description
===================
......
.. _smtk-bindings:
******************
---------------
SMTK's Bindings
******************
---------------
SMTK is written in C++ and uses pybind11_ to generate python bindings.
......
......@@ -30,32 +30,15 @@ SMTK also provides a uniform interface to several different
solid modeling kernels for preparing discretizations of your
simulation domain.
For instructions on obtaining, building, and installing
SMTK, clone the repository:
.. code:: sh
git clone https://gitlab.kitware.com/cmb/smtk.git
and follow the instructions in the :file:`ReadMe.md` file
in the top-level source directory.
The rest of this user's guide assumes you have built
and installed SMTK according to these instructions.
In addition to cloning anonymously as mentioned above,
you are also welcome to create an account on either
gitlab.kitware.com or github.com and fork the repository.
Forking the repository will allow you to submit contributions
back to SMTK for inclusion in later releases.
See :ref:`smtk-contributing` for more on how to
prepare and submit changes to SMTK.
.. toctree::
:maxdepth: 4
obtain-build-install.rst
overview.rst
attribute/index.rst
model/index.rst
mesh/index.rst
simulation/index.rst
bindings/index.rst
administration.rst
contributing.rst
......
.. _smtk-mesh-sys:
******************
------------------
SMTK's Mesh System
******************
------------------
SMTK's third major component is its meshing system,
which allows you to interact with multiple mesh generators
......
.. _smtk-model-sys:
*****************************
-----------------------------
SMTK's Geometric Model System
*****************************
-----------------------------
SMTK's second major component is its geometric modeling system,
which allows you to interact with multiple modeling sessions
......
-----------------------------------
Obtaining, Building, and Installing
-----------------------------------
For instructions on obtaining, building, and installing
SMTK, clone the repository:
.. code:: sh
git clone https://gitlab.kitware.com/cmb/smtk.git
and follow the instructions in the :file:`ReadMe.md` file
in the top-level source directory.
The rest of this user's guide assumes you have built
and installed SMTK according to these instructions.
In addition to cloning anonymously as mentioned above,
you are also welcome to create an account on either
gitlab.kitware.com or github.com and fork the repository.
Forking the repository will allow you to submit contributions
back to SMTK for inclusion in later releases.
See :ref:`smtk-contributing` for more on how to
prepare and submit changes to SMTK.
.. _smtk-overview:
-------------------------------
An Overview of SMTK's Subsytems
-------------------------------
SMTK's core library contains several subsystems,
each of which is covered in depth in sections that follow this one.
These subsystems are:
* The **attribute** system, which provides a way to specify how information should be
organized for scientific and engineering workflows, accept that information from users,
and ensure that it is consistent with the specification.
* The **model** system, which provides geometric modeling and allows you to tie
information from the attribute system to geometric entities (e.g., assign boundary conditions
in the attribute system to particular boundaries on a CAD model).
* The **mesh** system, which can manipulate meshes of geometric models; it provides a way
to propagate simulation attribute information from model entities onto meshes.
It also provides a way to run external mesh creation tools on the model.
* The **simulation** (also known as the **export**) system, which is a set of utilities
that lets you convert an attribute system, model, and mesh into an input deck for a simulation
using Python scripts (or C++ if you wish).
* A **common** system holding utility classes.
* Python **bindings** that enable SMTK to
be used *by* python scripts *and* SMTK to run python scripts as part of its normal operations.
* A set of **extension** libraries, which provide additional functionality but also introduce
dependencies on software beyond what the core smtk library already requires.
These are used to create applications built on SMTK.
------------------------
SMTK's Simulation System
------------------------
Once you have
a model or mesh and
an attribute system describing a simulation,
you are ready to create an input deck for the simulation.
One option is to have your simulation link directly to SMTK,
load the saved information from SMTK's native file formats,
and use SMTK to initialize the simulation.
Often this is not feasible, and so SMTK provides stubs
for writing a file in the format a simulation expects,
commonly known as an *input deck* [#f1]_.
We expect you will use python to write the input deck as
it is much simpler and easier to maintain a python script
than a large C++ code base to write what is usually a flat
text file.
The :smtk:`smtk::simulation::ExportSpec` class aggregates
all of the information you should need to write the input deck:
* an attribute system holding simulation parameters
* an attribute system holding locations of files involved in the export
* an object that provides methods for querying the analysis grid (be it a model or mesh).
Your python export script is expected to take a single argument (an
instance of ExportSpec) and write whatever files are needed to run the simulation.
.. [#f1] This term is historical, as many of the first simulations
were run on computers that used punch cards for offline
storage; a deck of punch cards holding simulation parameters
was often kept as a way to reproduce results for a simulation
run used in a report or journal article.
set(smtkCommonPythonTests
version
uuidGenerator
datetimezonepairtest
)
......
#=============================================================================
#
# Copyright (c) Kitware, Inc.
# All rights reserved.
# See LICENSE.txt for details.
#
# This software is distributed WITHOUT ANY WARRANTY; without even
# the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
# PURPOSE. See the above copyright notice for more information.
#
#=============================================================================
import os
import sys
import unittest
import smtk
from smtk import common
import smtk.testing
from smtk.simple import *
class Version(unittest.TestCase):
def test(self):
major = smtk.common.Version.major()
minor = smtk.common.Version.minor()
patch = smtk.common.Version.patch()
combined = smtk.common.Version.combined()
number = smtk.common.Version.number()
mmp = '%d.%d.%d' % (major, minor, patch)
intversion = (1000 * (100 * major + minor) + patch)
self.assertEqual(
number, mmp, 'Version number should be formatted as major.minor.patch.')
self.assertEqual(combined, intversion,
'Combined integer version miscalculated.')
readme = open(os.path.join(smtk.testing.SOURCE_DIR, 'doc/index.rst'))
readme.readline() # Skip title flare
readmeVersion = readme.readline().strip()
readmeMatch = 'Version %s' % number
self.assertTrue(readmeVersion.find(readmeMatch) > 0,
"""Mismatched version numbers in CMakeLists.txt and doc/index.rst.
Do not take version bumps lightheartedly.
Do not remove this test nor the line in the doc/index.rst
with the explicit version number; it is your friend.
This test exists as a reminder to follow the release
procedure and verify that git branches and tags, signed
source and/or binary packages, updated documentation,
and all other release artifacts have been produced.
All tests should be passing and all issues assigned to
the milestone for this release (you **do** have a
milestone for this release, right?) have been closed.
From index.rst: %s
From smtkCore (via CMakeLists.txt): %s
""" % (readmeVersion, readmeMatch))
if __name__ == '__main__':
smtk.testing.process_arguments()
unittest.main()
2.0.0-development
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