DM-33518: Some docstring cleanups

doc/index.rst

@@ -10,5 +10,4 @@ base documentation preview
    :maxdepth: 1
 
    lsstDebug/index
-   base/index
    lsst.base/index

doc/lsst.base/index.rst

@@ -23,3 +23,7 @@ Python API reference
 
 .. automodapi:: lsst.base
    :no-main-docstr:
+   :skip: getCondaPackages
+   :skip: getEnvironmentPackages
+   :skip: getPythonPackages
+   :skip: getVersionFromPythonModule

doc/lsstDebug/index.rst

@@ -18,6 +18,68 @@ Contributing
 ``lsstDebug`` is developed at https://github.com/lsst/base.
 You can find Jira issues for this module under the `base <https://jira.lsstcorp.org/issues/?jql=project%20%3D%20DM%20AND%20component%20%3D%20base>`_ component.
 
+.. _lsstDebug-using:
+
+Using lsstDebug to control debugging output
+===========================================
+
+The class `lsstDebug`` can be used to turn on debugging output in a non-intrusive way.
+For example, the variable ``lsstDebug.Info("lsst.meas.astrom.astrom").debug`` is used to control debugging output from the ``lsst.meas.astrom.astrom`` module.
+
+You may interrogate `lsstDebug` for any string in `sys.modules`, i.e. for the ``__name__`` of any package that has been imported;  for example, if the ``Robert.Hugh.Lupton`` package is loaded then ``lsstDebug.Info("Robert.Hugh.Lupton").parameter`` will return `False` for any named parameter that has not already been set to True elsewhere.
+
+The convention is that the name (``lsst.meas.astrom.astrom``) is the  ``__name__`` of the module, so the source code will typically look something like:
+
+.. code-block:: python
+
+   import lsstDebug
+
+   print(lsstDebug.Info(__name__).display)
+
+which will print `False` unless ``lsstDebug.Info(\__name__).display`` has somehow been set to `True`.
+
+Why is this interesting?
+Because you can replace `lsstDebug.Info` with your own version, *e.g.* if you put
+
+.. code-block:: python
+
+   import lsstDebug
+
+   def DebugInfo(name):
+       di = lsstDebug.getInfo(name)  # N.b. lsstDebug.Info(name) would call us recursively
+       if name == "foo":
+           di.display = True
+
+       return di
+
+
+   lsstDebug.Info = DebugInfo
+
+into a file ``debug.py`` available in the ``PYTHONPATH`` and
+
+.. code-block:: python
+
+   import lsstDebug
+
+   print("display is", lsstDebug.Info(__name__).display)
+
+into ``foo.py``, then
+
+.. code-block:: bash
+
+    $ python -c "import foo"
+    display is False
+
+but
+
+.. code-block:: bash
+
+    $ python -c "import debug; import foo"
+    display is True
+
+The ``pipetask run`` command line interface supports a flag ``--debug`` to import ``debug.py`` from your ``PYTHONPATH``.
+
+
 .. _lsstDebug-pyapi:
 
 Python API reference

doc/mainpage.dox

@@ -4,65 +4,7 @@ namespace lsst {
 
 \section baseIntro Introduction
 
-Functionality that shgould always be available to any LSST code
-
-- \ref baseDebug
-*/
-
-/**
-\page baseDebug  Using lsstDebug to control debugging output
-
-The class \link lsstDebug \endlink can be used to turn on debugging output in a non-intrusive way.  For example,
-the variable \c lsstDebug.Info("lsst.meas.astrom.astrom").debug is used to control debugging output from
-the lsst.meas.astrom.astrom module.
-
-You may interrogate \c lsstDebug for any string in \c sys.modules, i.e. for the \c \__name__ of any package
-that has been imported;  for example, if the \c Robert.Hugh.Lupton package is loaded then
-\c lsstDebug.Info("Robert.Hugh.Lupton").parameter will return False for any named parameter that has not
-already been set to True elsewhere.
-
-The convention is that the name ("lsst.meas.astrom.astrom") is the \c \__name__ of the module, so the
-source code will typically look something like:
-\code
-    import lsstDebug
-
-    print lsstDebug.Info(__name__).display
-\endcode
-which will print \c False unless \c lsstDebug.Info(\__name__).display has somehow been set to \c True.
-
-Why is this interesting?  Because you can replace \c lsstDebug.Info with your own version, \em e.g.
-if you put
-\code
-import lsstDebug
-
-def DebugInfo(name):
-    di = lsstDebug.getInfo(name)        # N.b. lsstDebug.Info(name) would call us recursively
-    if name == "foo":
-        di.display = True
-
-    return di
-
-lsstDebug.Info = DebugInfo
-\endcode
-into a file \b debug.py available in the \c PYTHONPATH and
-\code
-    import lsstDebug
-
-    print "display is", lsstDebug.Info(__name__).display
-\endcode
-into \b foo.py, then
-\code
-$ python -c "import foo"
-display is False
-\endcode
-but
-\code
-$ python -c "import debug; import foo"
-display is True
-\endcode
-
-The \link lsst.pipe.base.cmdLineTask.CmdLineTask command line task\endlink interface supports a
-flag \c --debug to import \b debug.py from your \c PYTHONPATH
+Functionality that should always be available to any LSST code
 
 */
 }

python/lsstDebug.py

@@ -40,7 +40,7 @@ class Info:
 
         display = lsstDebug.Info(__name__).display
 
-    will set display to False, unless display has been set with
+    will set display to `False`, unless display has been set with
 
     .. code-block:: python
 
@@ -70,7 +70,7 @@ def DebugInfo(name):
 
     Raises
     ------
-    KeyError :
+    KeyError
         Raised if ``modname`` is not loaded.
     """
     def __init__(self, modname):
@@ -95,7 +95,7 @@ def __setattr__(self, what, value):
 def getDebugFrame(debugDisplay, name):
     """
     Attempt to extract a frame for displaying a product called ``name``
-    from the ```debugDisplay`` variable.
+    from the ``debugDisplay`` variable.
 
     Per the above, an instance of `Info` can return an arbitrary object
     (or nothing) as its ``display`` attribute. It is convenient -- though not
@@ -108,7 +108,7 @@ def getDebugFrame(debugDisplay, name):
     Parameters
     ----------
     debugDisplay : `object`
-        The contents of lsstDebug.Info(__name__).display.
+        The contents of ``lsstDebug.Info(__name__).display``.
     name : `str`
         The name of the data product to be displayed.