Restructure analysis tools docs landing page.

doc/lsst.analysis.tools/index.rst

@@ -2,25 +2,22 @@
 
 .. _lsst.analysis.tools:
 
-###################
+===================
 lsst.analysis.tools
-###################
+===================
 
-.. Paragraph that describes what this Python module does and links to related modules and frameworks.
+The Analysis Tools package is designed to assist in the creation of quality assurance (QA) plots and metrics from the outputs of a data reduction pipeline.
+The intention is that users have the flexibility to construct complex data analysis tasks from a set of simple building blocks.
+In this sense, a series of consistent, repeatable and high-quality plots and metrics can be generated for any given dataset.
 
-``analysis_tools`` is the plotting and metric framework that is used to perform QA on the pipeline products.
-It is a very powerful way to explore and interact with the pipeline outputs.
+.. _lsst.analysis.tools-using:
 
-.. .. _lsst.analysis.tools-using:
-
-Using lsst.analysis.tools
-=========================
+Using Analysis Tools
+====================
 
 For a tutorial on working with
 ``analysis_tools`` please see the :ref:`getting started guide <analysis-tools-getting-started>`.
 
-.. toctree linking to topics related to using the module's APIs.
-
 .. toctree::
    :glob:
    :maxdepth: 1
@@ -29,53 +26,32 @@ For a tutorial on working with
    action-types
    plot-types
 
+.. _lsst.analysis.tools-help:
+
 Need Help?
 ==========
 
-If you get stuck with ``analysis_tools`` then feel free to reach out to the ``#rubinobs-analysis-tools``
-channel on slack and hopefully someone will help you!
-
-
-.. _lsst.analysis.tools-contributing:
-
-Contributing
-============
-
-``lsst.analysis.tools`` is developed at https://github.com/lsst/analysis_tools.
-You can find Jira issues for this module under the `analysis_tools <https://jira.lsstcorp.org/issues/?jql=project%20%3D%20DM%20AND%20component%20%3D%20analysis_tools>`_ component.
-
-.. If there are topics related to developing this module (rather than using it), link to this from a toctree placed here.
+If you have any questions regarding ``analysis_tools`` it is recommended that you post your question on `The Community Forum <https://community.lsst.org/>`_.
+Please also feel free to reach out on the ``#rubinobs-analysis-tools`` channel on the LSSTC Slack workspace.
 
-.. .. toctree::
-..    :maxdepth: 1
+.. _lsst.analysis_tools-pyapi:
 
-.. .. _lsst.analysis.tools-scripts:
-
-.. Script reference
-.. ================
-
-.. .. TODO: Add an item to this toctree for each script reference topic in the scripts subdirectory.
-
-.. .. toctree::
-..    :maxdepth: 1
-
-.. .. _lsst.analysis.tools-pyapi:
-
-Python API reference
+Python API Reference
 ====================
 
-.. NOTE: Skip the type definitions that cause the pipelines docs build to fail.
 .. automodapi:: lsst.analysis.tools
-   :no-main-docstr:
-   :no-inheritance-diagram:
-   :include-all-objects:
-   :skip: Vector
-   :skip: KeyedData
-   :skip: KeyedDataSchema
-   :skip: KeyedDataTypes
 .. automodapi:: lsst.analysis.tools.actions.plot
-   :no-inheritance-diagram:
 .. automodapi:: lsst.analysis.tools.actions.vector
-   :no-inheritance-diagram:
 .. automodapi:: lsst.analysis.tools.actions.scalar
-   :no-inheritance-diagram:
+
+.. _lsst.analysis_tools-contributing:
+
+Contributing
+============
+
+The ``lsst.analysis.tools`` package is developed at
+`github.com/lsst/analysis_tools <https://github.com/lsst/analysis_tools>`_.
+
+Jira issues relating to this package can be found using the
+`analysis_tools <https://jira.lsstcorp.org/issues/?jql=project%20%3D%20DM%20AND%20component%20%3D%20analysis_tools>`_
+component.

python/lsst/analysis/tools/__init__.py

@@ -21,19 +21,20 @@
 r"""This packages contains various analysis tools and PipelineTasks which
 run them.
 
-There are two types of primary tools within this package; `AnalysisMetrics
-and `AnalysisPlots`, both of which are specialized subclasses of `AnalysisTool`.
+There are two primary types of tools within this package: `AnalysisMetrics` and
+`AnalysisPlots`, both of which are specialized subclasses of `AnalysisTool`.
 
-`AnalysisTool`\ s are objects that have three stages; prep, process, and
-post-process. Creating a new `AnalysisTool` is the process of choosing (though
-configuration) what `AnalysisAction` will run for each of those stages.
+An `AnalysisTool` object has three stages: prep, process, and produce.
+Creating a new `AnalysisTool` is the process of choosing (through
+configuration) an `AnalysisAction` to run for each of those stages.
 
-`AnalysisTool`\ s and `AnalysisAction`\ s are subclasses of
-`~lsst.pex.config.configurableActions.ConfigurableAction`\ s. These objects are
-special types that are configured _prior_ to any code execution, and behave as
-functions at runtime. The configuration state of a
+`Both AnalysisTool` and `AnalysisAction` are subclasses of the
+`~lsst.pex.config.configurableActions.ConfigurableAction` class.
+These objects are special types that are configured *prior* to any code
+execution, and behave as functions at runtime.
+The configuration state of a
 `~lsst.pex.config.configurableActions.ConfigurableAction` is saved separately
-from the object itself, which allows
+from the object itself.
 """
 
 from .statistics import *