DOC #262 re-organize

prjemian · Mar 16, 2022 · 2973487 · 2973487
1 parent 258574b
commit 2973487
Show file tree

Hide file tree

Showing 15 changed files with 95 additions and 35 deletions.
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -0,0 +1,17 @@
+API
+##############
+
+The **spec2nexus** package application-programmer interface includes these modules:
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   charts
+   control_lines
+   diffractometers
+   plugin_core
+   scanf
+   singletons
+   utils
+   writer
diff --git a/docs/source/applications.rst b/docs/source/applications.rst
@@ -0,0 +1,13 @@
+Applications
+##############
+
+The **spec2nexus** package provides these applications:
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   spec2nexus
+   extractSpecScan
+   specplot
+   specplot_gallery
diff --git a/docs/source/contents.rst b/docs/source/contents.rst
@@ -5,22 +5,13 @@ Contents
    :maxdepth: 2
    :glob:
 
-   spec2nexus
-   extractSpecScan
-   specplot
-   specplot_gallery
-   spec
-   charts
-   specplot_custom_scan_macro
-   eznx
-   plugin_core
-   utils
-   scanf
-   singletons
-   writer
    install
-   unit_testing
    example_data
+   applications
+   libraries
+   howto
+   api
+   unit_testing
    changes
    license
 

diff --git a/docs/source/control_lines.rst b/docs/source/control_lines.rst
@@ -0,0 +1,11 @@
+.. index:: ! plugin
+
+:mod:`spec2nexus.control_lines`
+################################################
+
+source code documentation
+*************************
+
+.. automodule:: spec2nexus.control_lines
+    :members: 
+    :synopsis: Use the plugin system to manage the SPEC control key plugins.
diff --git a/docs/source/diffractometers.rst b/docs/source/diffractometers.rst
@@ -0,0 +1,11 @@
+.. index:: ! plugin
+
+:mod:`spec2nexus.diffractometers`
+################################################
+
+source code documentation
+*************************
+
+.. automodule:: spec2nexus.diffractometers
+    :members: 
+    :synopsis: Describe SPEC diffractometer geometry #G control lines.
diff --git a/docs/source/example_data.rst b/docs/source/example_data.rst
@@ -6,6 +6,9 @@
 Example data
 ############
 
+In addition to the example data files below, see the :ref:`example.1d.ascan`
+section an example of the NeXus HDF5 file written by **spec2nexus**.
+
 .. include:: ../../src/spec2nexus/data/README.txt
 
 Downloads

diff --git a/docs/source/how_to_write_plugin.rst b/docs/source/how_to_write_plugin.rst
@@ -1,8 +1,8 @@
 
 .. _how_to_write_plugin:
 
-How to write a custom plugin module
-###################################
+How to write a custom control line handling plugin module for *spec*
+######################################################################
 
 .. sidebar:: The code to write plugins has changed with release 2021.0.0.
 

diff --git a/docs/source/howto.rst b/docs/source/howto.rst
@@ -0,0 +1,9 @@
+How-to guides
+#############
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   how_to_write_plugin
+   specplot_custom_scan_macro
diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst
@@ -0,0 +1,11 @@
+Libraries
+##############
+
+The **spec2nexus** package provides these libraries:
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   spec
+   eznx
diff --git a/docs/source/nexus_layout/example_1d_scan.rst b/docs/source/nexus_layout/example_1d_scan.rst
@@ -1,3 +1,4 @@
+.. _example.1d.ascan:
 
 Example 1-D scan
 ++++++++++++++++

diff --git a/docs/source/plugin_core.rst b/docs/source/plugin_core.rst
@@ -48,17 +48,11 @@ These plugin modules are supplied:
 Writing a custom plugin
 ***********************
 
-While **spec2nexus** provides a comprehensive set of plugins
-to handle the common SPEC :index:`control line` control lines, custom control lines
-are used at many facilities to write additional scan data
-and scan metadata into the SPEC data file.  Custom plugins
-are written to process these additions.
-
-.. toctree::
-   :maxdepth: 2
-   :glob:
-
-   how_to_write_plugin
+While **spec2nexus** provides a comprehensive set of plugins to handle the
+common SPEC :index:`control line` control lines, custom control lines are used
+at many facilities to write additional scan data and scan metadata into the SPEC
+data file.  Custom plugins are written to process these additions.  See the
+:ref:`how_to_write_plugin` section for details.
 
 .. _control_line_table:
 

diff --git a/docs/source/spec2nexus.rst b/docs/source/spec2nexus.rst
@@ -22,7 +22,7 @@ Describe the NeXus File
 
 The NeXus file could be simple or complex, depending on the data available in
 the SPEC data file.  The content of the NeXus file is described in the following
-sections.
+sections.  See the :ref:`example.1d.ascan` section for an example.
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/specplot_custom_scan_macro.rst b/docs/source/specplot_custom_scan_macro.rst
@@ -1,8 +1,8 @@
 
 .. _how_to_write_custom_scan_macro_handling:
 
-How to write a custom scan handling for *specplot*
-##################################################
+How to write a custom scan handling class for *specplot*
+#########################################################
 
 Sometimes, it will be obvious that a certain scan macro never generates
 any plot images, or that the default handling creates a plot that

diff --git a/docs/source/utils.rst b/docs/source/utils.rst
@@ -1,8 +1,10 @@
 .. _utils:
 
-Common Methods: :mod:`spec2nexus.utils`
+:mod:`spec2nexus.utils`
 ##########################################
 
+Common methods used throughout the package.
+
 source code documentation
 *************************
 

diff --git a/src/spec2nexus/diffractometers.py b/src/spec2nexus/diffractometers.py
@@ -1,8 +1,5 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-
 """
-Describe SPEC #G control lines
+Describe SPEC diffractometer geometry #G control lines.
 
   #G0 ...       G[] array (geo mode, sector, etc)
   #G1 ...       U[] array (lattice constants, orientation reflections)