Merge pull request #385 from larrybradley/refresh-docs

Update and refresh narrative documentation

docs/changelog.rst

@@ -1,6 +1,5 @@
 .. _changelog:
 
-
 **************
 Full Changelog
 **************

docs/compound.rst

@@ -1,32 +1,44 @@
-
-.. _gs-compound:
-
-Combining regions
+Combining Regions
 =================
 
-There's a few ways to combine any two `~regions.Region` objects into a compound region,
-i.e. a `~regions.CompoundPixelRegion` or `~regions.CompoundSkyRegion` object.
+There are a few ways to combine any two `~regions.Region` objects
+into a compound region, i.e., a `~regions.CompoundPixelRegion` or
+`~regions.CompoundSkyRegion` object.
 
-* The ``&`` operator calls the ``__and__`` method which calls the :meth:`~regions.Region.intersection` method
-  to create an intersection compound region.
-* The ``|`` operator calls the ``__or__`` method which calls the :meth:`~regions.Region.union` method
-  to create a union compound region.
-* The ``^`` operator calls the ``__xor__`` method which calls the :meth:`~regions.Region.symmetric_difference` method
-  to create a symmetric difference compound region.
-
-.. code-block:: python
+Let's start by defining two sky regions::
 
     >>> from astropy.coordinates import Angle, SkyCoord
     >>> from regions import CircleSkyRegion
+
     >>> circle1 = CircleSkyRegion(
-    ...    center=SkyCoord(1,2, unit='deg', frame='galactic'),
-    ...    radius=Angle('5 deg')
-    ...    )
+    ...    center=SkyCoord(1, 2, unit='deg', frame='galactic'),
+    ...    radius=Angle('5 deg'))
     >>> circle2 = CircleSkyRegion(
-    ...    center=SkyCoord(-4,3, unit='deg', frame='galactic'),
-    ...    radius=Angle('3 deg'),
-    ...    )
-    >>> print(circle1 & circle2)
+    ...    center=SkyCoord(-4, 3, unit='deg', frame='galactic'),
+    ...    radius=Angle('3 deg'))
+
+
+Intersection (AND)
+------------------
+
+To create an intersection compound region, use either the ``&`` operator
+or the :meth:`~regions.Region.intersection` method::
+
+    >>> comp_region = circle1 & circle2
+    >>> print(comp_region)
+    Region: CompoundSkyRegion
+    region1: Region: CircleSkyRegion
+    center: <SkyCoord (Galactic): (l, b) in deg
+        (1., 2.)>
+    radius: 5.0 deg
+    region2: Region: CircleSkyRegion
+    center: <SkyCoord (Galactic): (l, b) in deg
+        (356., 3.)>
+    radius: 3.0 deg
+    operator: <built-in function and_>
+
+    >>> comp_region = circle1.intersection(circle2)
+    >>> print(comp_region)
     Region: CompoundSkyRegion
     region1: Region: CircleSkyRegion
     center: <SkyCoord (Galactic): (l, b) in deg
@@ -37,7 +49,62 @@ i.e. a `~regions.CompoundPixelRegion` or `~regions.CompoundSkyRegion` object.
         (356., 3.)>
     radius: 3.0 deg
     operator: <built-in function and_>
-    >>> print(circle1 ^ circle2)
+
+
+Union (OR)
+----------
+
+To create a union compound region, use either the ``|`` operator or the
+:meth:`~regions.Region.union` method::
+
+    >>> comp_region = circle1 | circle2
+    >>> print(comp_region)
+    Region: CompoundSkyRegion
+    region1: Region: CircleSkyRegion
+    center: <SkyCoord (Galactic): (l, b) in deg
+        (1., 2.)>
+    radius: 5.0 deg
+    region2: Region: CircleSkyRegion
+    center: <SkyCoord (Galactic): (l, b) in deg
+        (356., 3.)>
+    radius: 3.0 deg
+    operator: <built-in function or_>
+
+    >>> comp_region = circle1.union(circle2)
+    >>> print(comp_region)
+    Region: CompoundSkyRegion
+    region1: Region: CircleSkyRegion
+    center: <SkyCoord (Galactic): (l, b) in deg
+        (1., 2.)>
+    radius: 5.0 deg
+    region2: Region: CircleSkyRegion
+    center: <SkyCoord (Galactic): (l, b) in deg
+        (356., 3.)>
+    radius: 3.0 deg
+    operator: <built-in function or_>
+
+
+Symmetric Difference (XOR)
+--------------------------
+
+To create a symmetric difference compound region, use either the ``^``
+operator or the :meth:`~regions.Region.symmetric_difference` method::
+
+    >>> comp_region = circle1 ^ circle2
+    >>> print(comp_region)
+    Region: CompoundSkyRegion
+    region1: Region: CircleSkyRegion
+    center: <SkyCoord (Galactic): (l, b) in deg
+        (1., 2.)>
+    radius: 5.0 deg
+    region2: Region: CircleSkyRegion
+    center: <SkyCoord (Galactic): (l, b) in deg
+        (356., 3.)>
+    radius: 3.0 deg
+    operator: <built-in function xor>
+
+    >>> comp_region = circle1.symmetric_difference(circle2)
+    >>> print(comp_region)
     Region: CompoundSkyRegion
     region1: Region: CircleSkyRegion
     center: <SkyCoord (Galactic): (l, b) in deg
@@ -49,5 +116,9 @@ i.e. a `~regions.CompoundPixelRegion` or `~regions.CompoundSkyRegion` object.
     radius: 3.0 deg
     operator: <built-in function xor>
 
+
+Example Illustrating Compound Regions
+-------------------------------------
+
 .. plot:: plot_compound.py
     :include-source: false

docs/contains.rst

@@ -1,74 +1,61 @@
-.. testsetup:
-    >>> from regions import make_example_dataset
-    >>> dataset = make_example_dataset(data='simulated')
-    >>> wcs = dataset.wcs
-
-.. _gs-contain:
-
-Checking for points inside regions
+Checking for Points Inside Regions
 ==================================
 
-Let's continue with sky and pixel regions defined in the :ref:`gs` section:
-
-.. code-block:: python
+Let's start by defining both a sky and pixel region::
 
     >>> from astropy.coordinates import Angle, SkyCoord
     >>> from regions import CircleSkyRegion, PixCoord, CirclePixelRegion
 
     >>> sky_center = SkyCoord(42, 43, unit='deg')
     >>> sky_radius = Angle(25, 'deg')
     >>> sky_region = CircleSkyRegion(sky_center, sky_radius)
-    >>> pixel_center = PixCoord(x=42, y=43)
-    >>> pixel_radius = 42
-    >>> pixel_region = CirclePixelRegion(pixel_center, pixel_radius)
-
     >>> print(sky_region)
     Region: CircleSkyRegion
     center: <SkyCoord (ICRS): (ra, dec) in deg
         (42., 43.)>
     radius: 25.0 deg
+
+    >>> pixel_center = PixCoord(x=42, y=43)
+    >>> pixel_radius = 42
+    >>> pixel_region = CirclePixelRegion(pixel_center, pixel_radius)
     >>> print(pixel_region)
     Region: CirclePixelRegion
     center: PixCoord(x=42, y=43)
     radius: 42
 
+Let's also define a WCS object using our example dataset::
 
-To test if a given point is inside or outside the regions, the Python ``in`` operator
-can be called, which calls the special ``__contains__`` method defined on the region classes:
+    >>> from regions import make_example_dataset
+    >>> dataset = make_example_dataset(data='simulated')
+    >>> wcs = dataset.wcs
 
-.. code-block:: python
+To test if a given point is inside or outside the region, the Python
+``in`` operator can be called::
 
     >>> from regions import PixCoord
     >>> PixCoord(55, 40) in pixel_region
     True
     >>> PixCoord(55, 200) in pixel_region
     False
 
-The ``in`` operator only works for scalar coordinates, because Python requires
-the return value to be a scalar bool, and only works for pixel regions. If you
-try to use ``in`` for non-scalar coordinates, you'll get a ``ValueError``:
-
-.. code-block:: python
+The ``in`` operator works only for scalar coordinates and pixel regions.
+If you try to use ``in`` for non-scalar coordinates, you'll get a
+`ValueError`::
 
     >>> pixcoord = PixCoord([50, 50], [10, 60])
     >>> pixcoord in pixel_region
     Traceback (most recent call last):
     ...
     ValueError: coord must be scalar. coord=PixCoord(x=[50 50], y=[10 60])
 
-If you have arrays of coordinates, use the `regions.SkyRegion.contains` or
-`regions.PixelRegion.contains` methods:
-
-.. code-block:: python
+If you have arrays of coordinates, use the `regions.SkyRegion.contains`
+or `regions.PixelRegion.contains` methods::
 
     >>> pixcoords = PixCoord.from_sky(sky_center, wcs)
     >>> pixel_region.contains(pixcoords)
     True
 
-Note that `regions.SkyRegion.contains`
-requires a WCS to be passed:
-
-.. code-block:: python
+Note that `regions.SkyRegion.contains` requires a WCS to be passed::
 
     >>> skycoord = SkyCoord([50, 50], [10, 60], unit='deg')
     >>> sky_region.contains(skycoord, wcs)

docs/contributing.rst

@@ -0,0 +1,46 @@
+Reporting Issues and Contributing
+=================================
+
+Reporting Issues
+----------------
+
+If you have found a bug in Regions please report it by
+creating a new issue on the `Regions GitHub issue tracker
+<https://github.com/astropy/regions/issues>`_. That requires creating a
+`free Github account <https://github.com/>`_ if you do not have one.
+
+Please include an example that demonstrates the issue that will allow
+the developers to reproduce and fix the problem. You may also be asked
+to provide information about your operating system and a full Python
+stack trace. The developers will walk you through obtaining a stack
+trace if it is necessary.
+
+
+Contributing
+------------
+
+Like the `Astropy`_ project, Regions is made both by and for its users.
+We accept contributions at all levels, spanning the gamut from fixing a
+typo in the documentation to developing a major new feature. We welcome
+contributors who will abide by the `Python Software Foundation Code of
+Conduct <https://www.python.org/psf/conduct/>`_.
+
+Regions follows the same workflow and coding guidelines as `Astropy`_.
+The following pages will help you get started with contributing fixes,
+code, or documentation (no git or GitHub experience necessary):
+
+* `How to make a code contribution <https://docs.astropy.org/en/latest/development/workflow/development_workflow.html>`_
+
+* `Coding Guidelines <https://docs.astropy.org/en/latest/development/codeguide.html>`_
+
+* `Developer Documentation <https://docs.astropy.org/en/latest/#developer-documentation>`_
+
+
+Getting Help
+------------
+
+Besides GitHub, you can `get help`_ from the community in a number of
+ways. There is also a slack channel for Regions hosted under the main
+Astropy slack.
+
+.. _get help: https://www.astropy.org/help.html