Change Sphinx docs automodapi to include-all-objects

CHANGES.rst

@@ -98,6 +98,7 @@ See the complete `Gammapy 0.7 merged pull requests list on Github <https://githu
 - [#1014] Introduce TSImageEstimator class (Axel Donath)
 - [#1013] Add Fermi-LAT 3FHL spatial models (Axel Donath)
 - [#845] Add background model component to SpectrumFit (Johannes King)
+- [#111] Include module-level variables in API docs (Christoph Deil)
 
 .. _gammapy_0p6_release:
 

docs/astro/population/index.rst

@@ -74,3 +74,4 @@ Reference/API
 
 .. automodapi:: gammapy.astro.population
     :no-inheritance-diagram:
+    :include-all-objects:

docs/astro/source/index.rst

@@ -33,3 +33,4 @@ Reference/API
 
 .. automodapi:: gammapy.astro.source
     :no-inheritance-diagram:
+    :include-all-objects:

docs/background/index.rst

@@ -44,3 +44,4 @@ Reference/API
 
 .. automodapi:: gammapy.background
     :no-inheritance-diagram:
+    :include-all-objects:

docs/catalog/index.rst

@@ -114,3 +114,4 @@ Reference/API
 
 .. automodapi:: gammapy.catalog
     :no-inheritance-diagram:
+    :include-all-objects:

docs/conf.py

@@ -50,6 +50,8 @@
 conf.read([os.path.join(os.path.dirname(__file__), '..', 'setup.cfg')])
 setup_cfg = dict(conf.items('metadata'))
 
+plot_html_show_source_link = False
+
 # -- General configuration ----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.

docs/cube/index.rst

@@ -49,4 +49,5 @@ Reference/API
 =============
 
 .. automodapi:: gammapy.cube
-    :no-inheritance-diagram:
+    :no-inheritance-diagram:
+    :include-all-objects:

docs/data/index.rst

@@ -55,3 +55,4 @@ Reference/API
 
 .. automodapi:: gammapy.data
     :no-inheritance-diagram:
+    :include-all-objects:

docs/datasets/index.rst

@@ -147,4 +147,4 @@ Reference/API
 
 .. automodapi:: gammapy.datasets
     :no-inheritance-diagram:
-
+    :include-all-objects:

docs/detect/index.rst

@@ -149,3 +149,4 @@ Reference/API
 
 .. automodapi:: gammapy.detect
     :no-inheritance-diagram:
+    :include-all-objects:

docs/image/index.rst

@@ -56,7 +56,9 @@ Reference/API
 
 .. automodapi:: gammapy.image
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.image.models
     :no-inheritance-diagram:
+    :include-all-objects:
 

docs/irf/index.rst

@@ -49,3 +49,4 @@ Reference/API
 
 .. automodapi:: gammapy.irf
     :no-inheritance-diagram:
+    :include-all-objects:

docs/maps/index.rst

@@ -369,6 +369,4 @@ Reference/API
 
 .. automodapi:: gammapy.maps
     :no-inheritance-diagram:
-
-
-
+    :include-all-objects:

docs/scripts/index.rst

@@ -111,3 +111,4 @@ Reference/API
 
 .. automodapi:: gammapy.scripts
     :no-inheritance-diagram:
+    :include-all-objects:

docs/spectrum/index.rst

@@ -85,6 +85,8 @@ Reference/API
 
 .. automodapi:: gammapy.spectrum
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.spectrum.models
     :no-inheritance-diagram:
+    :include-all-objects:

docs/stats/index.rst

@@ -120,3 +120,4 @@ Reference/API
 
 .. automodapi:: gammapy.stats
     :no-inheritance-diagram:
+    :include-all-objects:

docs/time/index.rst

@@ -115,4 +115,4 @@ Reference/API
 
 .. automodapi:: gammapy.time
     :no-inheritance-diagram:
-
+    :include-all-objects:

docs/utils/index.rst

@@ -169,42 +169,56 @@ Reference/API
 
 .. automodapi:: gammapy.utils.energy
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.units
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.coordinates
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.table
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.fits
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.root
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.random
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.distributions
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.scripts
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.testing
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.wcs
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.nddata
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.time
     :no-inheritance-diagram:
+    :include-all-objects:
 
 .. automodapi:: gammapy.utils.modeling
     :no-inheritance-diagram:
+    :include-all-objects:

gammapy/astro/population/simulate.py

@@ -13,8 +13,8 @@
 from ...utils.distributions import draw, pdf
 from ...utils.random import sample_sphere, sample_sphere_distance, get_random_state
 from ..source import SNR, SNRTrueloveMcKee, PWN, Pulsar
-from ..population import Exponential, FaucherSpiral, RMIN, RMAX, ZMIN, ZMAX, radial_distributions
-from ..population import VMIN, VMAX, velocity_distributions
+from ..population.spatial import Exponential, FaucherSpiral, RMIN, RMAX, ZMIN, ZMAX, radial_distributions
+from ..population.velocity import VMIN, VMAX, velocity_distributions
 
 __all__ = [
     'make_catalog_random_positions_cube',

gammapy/astro/population/spatial.py

@@ -1,13 +1,5 @@
 # Licensed under a 3-clause BSD style license - see LICENSE.rst
-"""Galactic radial source distribution probability density functions.
-
-Attributes
-----------
-radial_distributions : `~collections.OrderedDict`
-    Dictionary of available spatial distributions.
-
-    Useful for automatic processing.
-"""
+"""Galactic radial source distribution probability density functions."""
 from __future__ import absolute_import, division, print_function, unicode_literals
 from collections import OrderedDict
 import numpy as np
@@ -29,8 +21,6 @@
     'FaucherSpiral',
     'ValleeSpiral',
     'radial_distributions',
-    'RMIN', 'RMAX',
-    'ZMIN', 'ZMAX',
 ]
 
 # Simulation range used for random number drawing
@@ -512,14 +502,8 @@ def __init__(self):
         self.bar = dict(x=Quantity([x_0, x_1]), y=Quantity([y_0, y_1]))
 
 
-# TODO: this is not picked up in the HTML docs ... don't know why.
-# http://sphinx-doc.org/latest/ext/example_numpy.html
-# For now I add it in the module-level docstring in an `Attributes` section.
 radial_distributions = OrderedDict()
-"""Dictionary of available spatial distributions.
-
-Useful for automatic processing.
-"""
+radial_distributions.__doc__ = """Radial distribution (dict mapping names to classes)."""
 radial_distributions['CB98'] = CaseBattacharya1998
 radial_distributions['F06'] = FaucherKaspi2006
 radial_distributions['L06'] = Lorimer2006

gammapy/astro/population/tests/test_spatial.py

@@ -3,10 +3,10 @@
 import numpy as np
 import pytest
 from astropy.modeling.tests.test_models import Fittable1DModelTester
-from ...population import (FaucherKaspi2006, Lorimer2006,
-                           YusifovKucuk2004, YusifovKucuk2004B,
-                           Paczynski1990, CaseBattacharya1998,
-                           RMIN, RMAX, ZMIN, ZMAX, Exponential)
+from ..spatial import (FaucherKaspi2006, Lorimer2006,
+                       YusifovKucuk2004, YusifovKucuk2004B,
+                       Paczynski1990, CaseBattacharya1998,
+                       RMIN, RMAX, ZMIN, ZMAX, Exponential)
 from .test_velocity import velocity_models_1D
 
 radial_models_1D = {

gammapy/astro/population/tests/test_velocity.py

@@ -1,8 +1,8 @@
 # Licensed under a 3-clause BSD style license - see LICENSE.rst
 from __future__ import absolute_import, division, print_function, unicode_literals
-from ...population import (FaucherKaspi2006VelocityMaxwellian,
-                           Paczynski1990Velocity,
-                           FaucherKaspi2006VelocityBimodal, VMAX, VMIN)
+from ..velocity import (FaucherKaspi2006VelocityMaxwellian,
+                        Paczynski1990Velocity,
+                        FaucherKaspi2006VelocityBimodal, VMAX, VMIN)
 
 velocity_models_1D = {
 

gammapy/astro/population/velocity.py

@@ -11,7 +11,6 @@
     'FaucherKaspi2006VelocityBimodal',
     'Paczynski1990Velocity',
     'velocity_distributions',
-    'VMIN', 'VMAX',
 ]
 
 # Simulation range used for random number drawing
@@ -119,10 +118,7 @@ def evaluate(v, amplitude, v_0):
 
 
 velocity_distributions = OrderedDict()
-"""Dictionary of available distributions.
-
-Useful for automatic processing.
-"""
+velocity_distributions.__doc__ = """Velocity distributions (dict mapping names to classes)."""
 velocity_distributions['H05'] = FaucherKaspi2006VelocityMaxwellian
 velocity_distributions['F06B'] = FaucherKaspi2006VelocityBimodal
 velocity_distributions['F06P'] = Paczynski1990Velocity

gammapy/datasets/make.py

@@ -75,7 +75,7 @@ def sigma_energy_theta(energy, theta, sigma):
                                         )
 
 
-def make_test_observation_table(observatory_name='HESS', n_obs=10,
+def make_test_observation_table(observatory_name='hess', n_obs=10,
                                 az_range=Angle([0, 360], 'deg'),
                                 alt_range=Angle([45, 90], 'deg'),
                                 date_range=(Time('2010-01-01'),
@@ -431,7 +431,7 @@ def make_test_bg_cube_model(detx_range=Angle([-10., 10.], 'deg'),
 
 
 def make_test_dataset(outdir, overwrite=False,
-                      observatory_name='HESS', n_obs=10,
+                      observatory_name='hess', n_obs=10,
                       az_range=Angle([0, 360], 'deg'),
                       alt_range=Angle([45, 90], 'deg'),
                       date_range=(Time('2010-01-01'),
@@ -512,8 +512,8 @@ def make_test_dataset(outdir, overwrite=False,
 
     # create data store for the organization of the files
     # using H.E.S.S.-like dir/file naming scheme
-    if observatory_name == 'HESS':
-        scheme = 'HESS'
+    if observatory_name == 'hess':
+        scheme = 'hess'
     else:
         s_error = "Warning! Storage scheme for {}".format(observatory_name)
         s_error += "not implemented. Only H.E.S.S. scheme is available."

gammapy/datasets/tests/test_make.py

@@ -22,7 +22,7 @@ def test_make_test_psf_fits_table():
 
 
 def test_make_test_observation_table():
-    observatory_name = 'HESS'
+    observatory_name = 'hess'
     n_obs = 10
     random_state = np.random.RandomState(seed=0)
     obs_table = make_test_observation_table(observatory_name=observatory_name,

gammapy/image/models/shapes.py

@@ -402,8 +402,9 @@ def bounding_box(self):
                 (x_0 - width, x_0 + height / 2))
 
 
+# TODO: change this to a model registry
 morph_types = OrderedDict()
-"""Available morphology types."""
+morph_types.__doc__ = """Spatial model registry (`~collections.OrderedDict`)."""
 morph_types['delta2d'] = Delta2D
 morph_types['gauss2d'] = Gaussian2D
 morph_types['shell2d'] = Shell2D

gammapy/scripts/data_show.py

@@ -32,10 +32,6 @@ def data_show_main(filename, filetype, do_plot):
 
     Use the `gammapy-data-browser` to browse / check lots of files.
     """
-    if do_plot:
-        import matplotlib.pyplot as plt
-        plt.style.use('fivethirtyeight')
-
     if filetype == 'events':
         show_events(filename, do_plot)
     elif filetype == 'aeff':

gammapy/utils/coordinates/other.py

@@ -10,6 +10,7 @@
     'motion_since_birth', 'polar', 'D_SUN_TO_GALACTIC_CENTER',
 ]
 
+# TODO: replace this with the default from the Galactocentric frame in astropy.coordinates
 D_SUN_TO_GALACTIC_CENTER = Quantity(8.5, 'kpc')