Docs: update to reflect new and updated functionality, support RTD

Move to the Read-The-Docs theme and MathJaX for inline mathematics.

The Read-The-Docs build uses the standalone version of Sherpa provided as a
conda package for this build. This means that the documentation can not be
generated at build time, since there is no support for the required XSPEC
models in this version of CIAO. Note that the Sherpa version is not
versioned, but there is a restriction to python 3.5.

Reorganize the documentation so that there are multiple pages.

We have not yet integrarated the standalone and CIAO versions of the
Sherpa documentation (and may never do so). For now switch to the
standalone version for the "sherpa.astro.ui" layer commands (via the
reference links) since they are more up-to-date (but less detailed)
than the CIAO ahelp versions.

docs/_templates/autosummary/base.rst

@@ -0,0 +1,10 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{{ objname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/_templates/autosummary/class.rst

@@ -0,0 +1,65 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{{ objname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :show-inheritance:
+
+   {% if '__init__' in methods %}
+     {% set caught_result = methods.remove('__init__') %}
+   {% endif %}
+
+   {% block attributes_summary %}
+   {% if attributes %}
+
+   .. rubric:: Attributes Summary
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}
+
+   {% block methods_summary %}
+   {% if methods %}
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes_documentation %}
+   {% if attributes %}
+
+   .. rubric:: Attributes Documentation
+
+   {% for item in attributes %}
+   .. autoattribute:: {{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}
+
+   {% block methods_documentation %}
+   {% if methods %}
+
+   .. rubric:: Methods Documentation
+
+   {% for item in methods %}
+   .. automethod:: {{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}

docs/_templates/autosummary/module.rst

@@ -0,0 +1,41 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{{ objname }}
+{{ underline }}
+
+.. automodule:: {{ fullname }}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: Functions
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: Classes
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: Exceptions
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/changes.rst

@@ -0,0 +1,145 @@
+
+.. include:: references.rst
+
+*******	     
+Changes
+*******
+
+.. _changes_020:
+
+Version 0.2.0
+=============
+
+Overview
+--------
+
+The code has been updated to run with Python 3 and can now be
+installed from `PyPI`_. Documentation has been moved to
+`Read The Docs <https://deproject.readthedocs.io/>`_.
+
+The deproject module now requires Astropy_, which can be
+`installed within CIAO 4.11 <http://cxc.harvard.edu/ciao/scripting/index.html#install>`_. The three main areas where Astropy functionality is
+used are:
+
+- the use of `Astropy Quantity <http://docs.astropy.org/en/stable/units/>`_
+  values (both for arguments to methods and returned values);
+- `Astropy Data Tables <http://docs.astropy.org/en/stable/table/>`_
+  are used to return tabular data;
+- and Cosmology calculations now use the `Astropy cosmology
+  module <http://docs.astropy.org/en/stable/cosmology/>`_ rather than
+  the `cosmocalc` module.
+
+The :py:func:`~deproject.deproject.deproject_from_xflt` helper function
+has been introduced, which uses the ``XFLT0001`` to ``XFLT0005``
+keywords in the input files to determine the annulus parameters (radii
+and covering angle). The covering angle (:math:`\theta`) can now vary per
+annulus.
+
+Error values can now be generated using the onion-peeling approach,
+for the confidence and covariance methods, and the values are returned
+as an Astropy Table. Parameter values can now be tied together (to
+combine annuli to try and avoid "ringing"). There is improved support
+for accessing and plotting values.
+
+Details
+-------
+
+The code has been re-arranged into the ``deproject`` package, which
+means that you really should say ``from deproject.deproject import
+Deproject``, but the ``deproject`` module re-exports
+:py:mod:`deproject.deproject` so that existing scripts still work, and
+you do not not have to type in the same word multiple times! The
+package has been updated so that it is available on `PyPI`_.
+
+The scaling between shells (calculated from the intersection between
+spheres and cylinders) was limited to 5 decimal places, which could
+cause problems with certain choices of annuli (such as an annulus
+making no contribution to interior annuli). This restriction has been
+removed.
+
+Added support for per-annulus ``theta`` values (that is, each annulus
+can have a different opening angle). The ``radii``, ``theta``, and
+``angdist`` parameters to :py:class:`~deproject.deproject.Deproject`
+all now require values that is an
+`Astropy quantity <http://docs.astropy.org/en/stable/units/>`_ rather
+than a dimensionless value.
+
+Added the :py:func:`~deproject.deproject.deproject_from_xflt` helper
+function, which creates a :py:class:`~deproject.deproject.Deproject`
+instance from PHA files which contain the XSPEC XFLT0001 to XFLT0005
+keywords (as used by the `projct`_ model), rather than specifying the
+values from the command line. The routine will error out if the
+keywords indicate elliptical annuli, and the default is to assume the
+radii are in arcseconds, but a scaling factor can be given if the
+radii are in some other units (such as pixels).
+
+Added the :py:meth:`~deproject.deproject.Deproject.guess` method to do
+an initial fit to each annulus, following the approach suggested in
+the `XSPEC`_ documentation for `projct`_, by just fitting the
+individual (not de-projected) models to each annulus. This can help
+speed up the deproject fit -
+:py:meth:`~deproject.deproject.Deproject.fit` - as well as help avoid
+the fit getting stuck in a local minimum.
+
+Added :py:meth:`~deproject.deproject.Deproject.covar` and
+:py:meth:`~deproject.deproject.Deproject.conf` methods that estimate
+errors - using the covariance and confidence methods respectively -
+using the onion-skin model (i.e. the errors on the outer annuli are
+evaluated, then this component is frozen and the errors on the next
+annulus are evaluated).
+
+The :py:meth:`~deproject.deproject.Deproject.fit`,
+:py:meth:`~deproject.deproject.Deproject.conf`, and
+:py:meth:`~deproject.deproject.Deproject.covar` methods now all return
+Astropy Tables containing the results per annulus. These values can
+also be retrieved with the
+:py:meth:`~deproject.deproject.Deproject.get_fit_results`,
+:py:meth:`~deproject.deproject.Deproject.get_conf_results`, or
+:py:meth:`~deproject.deproject.Deproject.get_covar_results` methods. A
+number of columns (radii and density) are returned as Astropy
+quantities.
+
+The ``cosmocalc`` module has been removed and the `Astropy cosmology
+module <http://docs.astropy.org/en/stable/cosmology/>`_ is used
+instead. This is only used if the angular-diameter distance to the
+source is calculated rather than explicitly given. The default
+cosmology is now set to `Planck15
+<http://docs.astropy.org/en/stable/cosmology/index.html#built-in-cosmologies>`_.
+
+Values, as a function of radius, can be plotted with a number of new
+methods: :py:meth:`~deproject.deproject.Deproject.fit_plot`,
+:py:meth:`~deproject.deproject.Deproject.conf_plot`, and
+:py:meth:`~deproject.deproject.Deproject.covar_plot` display the last
+fit results (with the last two including error estimates), and the
+:py:meth:`~deproject.deproject.Deproject.par_plot` and
+:py:meth:`~deproject.deproject.Deproject.density_plot` methods show
+the current values. These support a number of options, including
+switching between angular and physical distances for the radii.
+
+The :py:meth:`~deproject.deproject.Deproject.get_shells` method has
+been added to make it easy to see which annuli are combined together,
+and the :py:meth:`~deproject.deproject.Deproject.get_radii` method to
+find the radii of the annuli (in a range of units).
+
+Added the :py:meth:`~deproject.deproject.SpecStack.tie_par` and
+:py:meth:`~deproject.deproject.SpecStack.untie_par` methods to make it
+easy to tie (or untie) parameters in neighbouring annuli. The
+onion-skin approach - used when fitting or running an error analysis -
+recognizes annuli that are tied together and fits these
+simultaneously, rather than individually.
+
+The :py:meth:`~deproject.deproject.Deproject.set_source` method can
+now be called multiple times (previously it would lead to an error).
+
+Added error checking for several routines, such as
+:py:meth:`~deproject.deproject.SpecStack.thaw` when given an
+unknown parameter name.
+
+Updated to support Python 3.5 and to have better support when the
+``pylab`` backend is selected. Support for the ChIPS backend is
+limited. A basic test suite has been added.
+
+Version 0.1.0
+=============
+
+Initial version.

docs/conf.py

@@ -11,22 +11,42 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import os
+import sys
 
-# If your extensions are in another directory, add it here. If the directory
-# is relative to the documentation root, use os.path.abspath to make it
-# absolute, like shown here.
-sys.path.append(os.path.abspath('../'))
+import sphinx_rtd_theme
+
+# Try and let Sherpa be found.
+#
+if os.path.split(os.getcwd())[1] == 'docs':
+    sys.path.insert(0, os.path.abspath('../src/'))
+
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 # General configuration
 # ---------------------
 
+# sphinx.ext.napoleon needs 1.3, although it is unlikely any modern system has
+# anything as old that this is important.
+#
+needs_sphinx = '1.3'
+
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.inheritance_diagram',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon'
+]
+
+napoleon_google_docstring = False
+
+autosummary_generate = True
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['.templates']
+templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -39,16 +59,16 @@
 
 # General information about the project.
 project = u'deproject'
-copyright = u'2009, Tom Aldcroft'
+copyright = u'2009, 2019 Tom Aldcroft'
 
 # 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 = '0.1'
+version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1.3'
+release = '0.2.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -84,14 +104,30 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# Graphviz based on values from AstroPy - see
+# https://github.com/astropy/sphinx-astropy/blob/master/sphinx_astropy/conf/v1.py
+#
+graphviz_output_format = "svg"
+
+graphviz_dot_args = [
+    '-Nfontsize=10',
+    '-Nfontname=Helvetica Neue, Helvetica, Arial, sans-serif',
+    '-Efontsize=10',
+    '-Efontname=Helvetica Neue, Helvetica, Arial, sans-serif',
+    '-Gfontsize=10',
+    '-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif'
+]
+
 
 # Options for HTML output
 # -----------------------
 
-# The style sheet to use for HTML and HTML Help pages. A file of that name
-# must exist either in Sphinx' static/ path, or in one of the custom paths
-# given in html_static_path.
-html_style = 'default.css'
+# html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+
+# html_theme_options = {}
+# html_theme_path = []
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -112,11 +148,16 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['.static']
+#
+# html_static_path = ['_static']
+
+# html_extra_path = []
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+
+# I believe this is what AstroPy is doing
+html_last_updated_fmt = '%d %b %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.