Merge pull request #511 from mwoehlke-kitware/update-manual

Update manual
Kitware · Aug 20, 2021 · 5980066 · 5980066
2 parents 0af7fe4 + f451af9
commit 5980066
Show file tree

Hide file tree

Showing 9 changed files with 463 additions and 115 deletions.
diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
@@ -0,0 +1,18 @@
+pre.wrap {
+  white-space: pre-wrap !important;
+}
+
+pre.literal-block,
+.filepath
+{
+  font-size: 75%;
+  font-family: monospace;
+  background: #f8f8f8;
+  color: #333;
+}
+
+.filepath {
+  white-space: pre-wrap;
+  border: 1px solid #e1e4e5;
+  padding: 2px 5px;
+}
diff --git a/doc/advancedconfig.rst b/doc/advancedconfig.rst
@@ -2,65 +2,107 @@
 
 .. include:: version.rst
 
-================================
+==============================
 Advanced Configuration Options
-================================
-
-Most users should not need these advanced features, but some may be interested.
-
-Changing Frame Sampling Rate
 ==============================
 
-By default, all video frames are loaded when opening a video (though not all are processed in feature tracking).  If the number of frames is too large to manage it is possible to
-read only every Nth frame by changing a setting in the project configuration.  First close the application.  Next open the project .conf file in a text editor like Notepad.  Look for
-the following line:
+Most users should not need these advanced features,
+but some may be interested.
 
-**video_reader:filter:output_nth_frame= 1**
-
-Increase the number from 1 to 10 to sample every 10th frame, for example.  Save the .conf file in the text editor and open that file again in the TeleSculptor application.
+Changing Frame Sampling Rate
+============================
 
-Modifying Algorithm Parameters
-================================
+By default, all video frames are loaded when opening a video
+(though not all are processed in feature tracking).
+If the number of frames is too large to manage
+it is possible to read only every Nth frame
+by changing a setting in the project configuration.
+First, close the application.
+Next, open the project :path:`.conf` file in a text editor like Notepad.
+Look for the following line:
 
-TeleSculptor is a highly configurable application, though most of the configuration options are not yet exposed to the user interface.  Each tool in the compute menu calls an
-algorithm from the KWIVER toolkit and each algorithm is configurable at run time.  Algorithms can even be swapped out for other algorithms at run time.  One can contribute a new
-algorithm without recompiling TeleSculptor by dropping in a new DLL and updating the configuration files.  All this configurability is managed with configuration files.  The project
-file is one example of configuration file, but there are also many default configuration files loaded by TeleSculptor at run time.  The default configuration files for a standard
-install path are found in these two locations:
+.. code-block:: bash
 
-**C:\\Program Files\\TeleSculptor** |space| |version| **\\share\\telesculptor\\** |version| **\\config**
+  video_reader:filter:output_nth_frame=1
 
-**C:\\Program Files\\TeleSculptor** |space| |version| **\\share\\kwiver\\1.5.0\\config**
+Increase the number from 1 to 10 to sample every tenth frame, for example.
+Save the :path:`.conf` file in the text editor
+and open that file again in the TeleSculptor application.
 
-TeleSculptor specific configurations are found in the first directory and these include configurations for KWIVER algorithms found in the second directory.  It is recommended that
-you not modify these values, but instead copy some of these files into your project directory and modify the copies.  TeleSculptor will load configuration files from the project
-directory first.  Each of the tools in the *Compute* menu loads a configuration file when it is run.  These have names starting with a "gui\_” prefix.  For example:
+Modifying Algorithm Parameters
+==============================
 
+TeleSculptor is a highly configurable application,
+though most of the configuration options
+are not yet exposed to the user interface.
+Each tool in the compute menu calls an algorithm from the KWIVER toolkit
+and each algorithm is configurable at run time.
+Algorithms can even be swapped out for other algorithms at run time.
+One can contribute a new algorithm without recompiling TeleSculptor
+by dropping in a new :path:`.dll` and updating the configuration files.
+All this configurability is managed with configuration files.
+The project file is one example of configuration file,
+but there are also many default configuration files
+loaded by TeleSculptor at run time.
+The default configuration files for a standard install path
+are found in these two locations:
+
+.. parsed-literal::
+  :class: wrap
+
+  C: |backslash| Program Files |backslash| TeleSculptor |version|
+  |backslash| share |backslash| telesculptor |backslash| |version|
+  |backslash| config
+
+.. parsed-literal::
+  :class: wrap
+
+  C: |backslash| Program Files |backslash| TeleSculptor |version|
+  |backslash| share |backslash| kwiver |backslash| |kwiver_version|
+  |backslash| config
+
+TeleSculptor specific configurations are found in the first directory
+and these include configurations for KWIVER algorithms
+found in the second directory.
+It is recommended that you not modify these values,
+but instead copy some of these files into your project directory
+and modify the copies.
+TeleSculptor will load configuration files from the project directory first.
+Each of the tools in the *Compute* menu
+loads a configuration file when it is run.
+These have names starting with a :path:`gui\_` prefix.
+For example:
 
 .. table::
    :align: center
 
-   +---------------------------+----------------------------------+
-   | Compute Menu Name         | Configuration File Entry Point   |
-   +===========================+==================================+
-   | Track Features            | gui_track_features.conf          |
-   +---------------------------+----------------------------------+
-   | Estimate Camera/Landmarks | gui_initialize.conf              |
-   +---------------------------+----------------------------------+
-   | Save Frames               | gui_frame_image_writer.conf      |
-   +---------------------------+----------------------------------+
-   | Batch Compute Depth Maps  | gui_compute_depth.conf           |
-   +---------------------------+----------------------------------+
-   | Fuse Depth Maps           | gui_integrate_depth_maps.conf    |
-   +---------------------------+----------------------------------+
-
-
-Most of these configuration files also reference other configuration files with an “include” statement.  Configuration values for tools can also be added to the project file but
-copying the GUI configuration files into the project directory adds more flexibility because these files are reloaded each time the tool is run, which allows changing parameters
-between runs without loading the project.
-
-As an example, consider changing the maximum number of frames to use in the feature tracker.  First copy **gui_track_features.conf** into your project directory.  Open this file and
-look for the following section:
+   +---------------------------+---------------------------------------+
+   | Compute Menu Name         | Configuration File Entry Point        |
+   +===========================+=======================================+
+   | Track Features            | :path:`gui_track_features.conf`       |
+   +---------------------------+---------------------------------------+
+   | Estimate Camera/Landmarks | :path:`gui_initialize.conf`           |
+   +---------------------------+---------------------------------------+
+   | Save Frames               | :path:`gui_frame_image_writer.conf`   |
+   +---------------------------+---------------------------------------+
+   | Batch Compute Depth Maps  | :path:`gui_compute_depth.conf`        |
+   +---------------------------+---------------------------------------+
+   | Fuse Depth Maps           | :path:`gui_integrate_depth_maps.conf` |
+   +---------------------------+---------------------------------------+
+
+Most of these configuration files also
+reference other configuration files with an ``include`` statement.
+Configuration values for tools can also be added to the project file
+but copying the GUI configuration files into the project directory
+adds more flexibility because these files
+are reloaded each time the tool is run,
+which allows changing parameters between runs
+without loading the project.
+
+As an example, consider
+changing the maximum number of frames to use in the feature tracker.
+First, copy :path:`gui_track_features.conf` into your project directory.
+Open this file and look for the following section:
 
 .. code-block:: bash
 
@@ -74,26 +116,52 @@ look for the following section:
    endblock
 
 
-Modify the line with “max_frame = 500” use a different value, such as 1000.  Note that you could also make this change in the project file by appending the following line:
+Modify the line with ``max_frame = 500``
+to use a different value, such as ``1000``.
+Note that you could also make this change
+in the project file by appending the following line:
 
 .. code-block:: bash
 
    feature_tracker:max_frames = 1000
 
-Note that the "max_frames" parameter is in the "feature_tracker" scope and scope must be specified either using block/endblock notation or with a prefix before a colon.
+Note that the ``max_frames`` parameter is in the ``feature_tracker`` scope
+and scope must be specified either using ``block``/``endblock`` notation
+or with a prefix before a colon.
 
 Printing all KLV metadata
 ===========================
 
-The TeleSculptor application loads KLV metadata and display it in a viewer, but there is no way to export this data in batch.  However, the installer does provide the kwiver command
-line tool that has an applet that will print out all metadata in a video.  This applet is called “dump_klv”. The default installation path is
+The TeleSculptor application loads KLV metadata and display it in a viewer,
+but there is no way to export this data in batch.
+However, the installer does provide the kwiver command line tool
+that has an applet that will print out all metadata in a video.
+This applet is called :path:`dump_klv`.
+The default installation path is:
+
+.. parsed-literal::
+  :class: wrap
+
+  C: |backslash| Program Files |backslash| TeleSculptor |version|
+  |backslash| bin |backslash| kwiver.exe
+
+To run :path:`dump_klv`, open up a command prompt
+(search for "cmd.exe" in the Start Menu).
+Then run:
 
-**C:\\Program Files\\TeleSculptor** |space| |version| **\\bin\\kwiver.exe**
+.. parsed-literal::
 
-To run dump_klv, open up a command prompt (search for cmd.exe in the Start Menu).  Then run
+  "C: |backslash| Program Files |backslash| TeleSculptor |version|
+  |backslash| bin |backslash| kwiver.exe" \
+  dump_klv video_file.mpeg
 
-**“C:\\Program Files\\TeleSculptor** |space| |version| **\\bin\\kwiver.exe” dump_klv video_file.mpeg**
+and replace :path:`video_file.mpeg`
+with the path to the video file to process.
+This will print out all the metadata.
+To redirect the output to a file use:
 
-and replace “video_file.mpeg” with the path to the video file to process.  This will print out all the metadata.  To redirect the output to a file use:
+.. parsed-literal::
 
-**“C:\\Program Files\\TeleSculptor** |space| |version| **\\bin\\kwiver.exe” dump_klv.exe video_file.mpeg > metadata.txt**
+  "C: |backslash| Program Files |backslash| TeleSculptor |version|
+  |backslash| bin |backslash| kwiver.exe" \
+  dump_klv video_file.mpeg > metadata.txt
diff --git a/doc/conf.py b/doc/conf.py
@@ -4,6 +4,9 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+from docutils import nodes
+from docutils.parsers.rst.states import Struct
+
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -18,9 +21,14 @@
 # -- Project information -----------------------------------------------------
 
 project = 'TeleSculptor'
+version = '1.2.0'
 copyright = '2021, Kitware, Inc.'
 author = 'Kitware, Inc.'
 
+kwiver_version = '1.6.0'
+
+repo_root = 'https://github.com/Kitware/TeleSculptor'
+relnotes_root = f'{repo_root}/blob/master/doc/release-notes'
 
 # -- General configuration ---------------------------------------------------
 
@@ -38,6 +46,14 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+rst_epilog = f'''
+.. include:: replacements.rst
+
+.. _Release Notes: {relnotes_root}/{version}.txt
+
+.. |kwiver_version| replace:: {kwiver_version}
+'''
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -59,5 +75,37 @@
 html_theme_options = {
     'logo_only': True,
 }
+
+html_css_files = [
+    'css/custom.css',
+]
+
 # The master toctree document
 master_doc = 'index'
+
+
+# -- Customizations ----------------------------------------------------------
+
+def make_parsed_text_role(class_names=[], node_class=nodes.inline):
+    def parsed_text_role(name, rawtext, text, lineno, inliner,
+                         options={}, content=[]):
+        # Prepare context for nested parsing
+        memo = Struct(document=inliner.document,
+                      reporter=inliner.reporter,
+                      language=inliner.language)
+
+        # Create parent node
+        options['classes'] = class_names
+        parent = node_class(rawtext, '', **options)
+
+        # Parse role text for markup and add to parent
+        processed, messages = inliner.parse(text, lineno, memo, parent)
+        parent += processed
+
+        # Return parent node, and any messages from nested parsing
+        return [parent], messages
+
+    return parsed_text_role
+
+def setup(app):
+    app.add_role('path', make_parsed_text_role(class_names=['filepath']))