Further documentation updates - refs #4

docs/source/conf.py

@@ -20,6 +20,11 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
 
+# Insert Requests' path into the system.
+sys.path.insert(0, os.path.abspath('../../psrqpy'))
+
+import psrqpy
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -61,9 +66,9 @@
 #
 
 # The short X.Y version.
-version = '0.3.1'
+version = psrqpy.__version__
 # The full version, including alpha/beta/rc tags.
-release = '0.3.1'
+release = psrqpy.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -123,9 +128,6 @@
     import sphinx_rtd_theme
     html_theme = 'sphinx_rtd_theme'
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-else:
-    sys.path.insert(0, os.path.abspath('../../'))
-    sys.path.insert(0, os.path.abspath('../../psrqpy'))
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/index.rst

@@ -18,7 +18,7 @@ Installation
 ============
 
 This package can be installed using ``pip`` via ``pip install psrqpy``. Alternatively
-the source code can be obtained from `here <https://github.com/mattpitkin/psrqpy>`_, and installed using::
+the source code can be obtained from `github <https://github.com/mattpitkin/psrqpy>`_, and installed using::
 
     python setup.py install
 

psrqpy/__init__.py

@@ -2,7 +2,7 @@
 
 """ A Python tool for interacting with the ATNF pulsar catalogue """
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 
 from .search import QueryATNF
 from .pulsar import Pulsar, Pulsars

psrqpy/pulsar.py

@@ -13,20 +13,17 @@
 
 class Pulsar(object):
     """
-    An object to hold a single pulsar
-    """
+    An object to hold a single pulsar. The class requires a pulsar name is required.
 
-    def __init__(self, psrname, version=None, **kwargs):
-        """
-        Set object attributes. A pulsar name is required.
+    Args:
+        psrname (str): a string containing a pulsar name
+        version (str): a string with the ATNF version to use for queries
 
-        :param psrname: a string containing a pulsar name
-        :param version: a string with the ATNF version to use for queries
+    Additional keyword arguments are any of the valid queriable pulsar parameters.
 
-        Additional keyword arguments are any of the valid queriable pulsar
-        parameters.
-        """
+    """
 
+    def __init__(self, psrname, version=None, **kwargs):
         self._name = psrname
         self._version = version if not version else get_version()
         self._ephemeris = None
@@ -67,7 +64,10 @@ def name(self):
     def __getitem__(self, key):
         """
         If the class has a attribute given by the key then return it, otherwise generate a
-        query for that key to set it
+        query for that key to set it.
+        
+        Args:
+            key (str): an item to get
         """
 
         ukey = key.upper()
@@ -132,15 +132,18 @@ def __getattr__(self, key):
 
     def __dir__(self):
         """
-        Set this to what ipython is returned for ipython's autocomplete (otherwise the custom
-        __getattr__ caused problems!)
+        Set this to what is returned for ipython's autocomplete (otherwise the custom
+        ``__getattr__`` caused problems!)
         """
 
         return self.keys()
 
     def have_ephemeris(self):
         """
-        Check whether we already have an ephemeris
+        Check whether we already have an ephemeris.
+        
+        Returns:
+            bool: True if an ephemeris has already be downloaded.
         """
 
         if self._ephemeris:
@@ -175,7 +178,8 @@ def set_ephemeris(self, ephem=None):
         """
         Set attributes from the returned ephemeris
 
-        :param ephem: the ephemeris string
+        Args:
+            ephem (str): the ephemeris string
         """
 
         if not self._ephemeris and ephem:
@@ -297,7 +301,10 @@ def add_pulsar(self, psr):
         """
         Add a pulsar into the object.
 
-        :param psr: a Pulsar object, or Pulsars object 
+        Args:
+            psr (:class:`~psrqpy.pulsar.Pulsar`, :class:`~psrqpy.pulsar.Pulsars`): a
+                :class:`~psrqpy.pulsar.Pulsar` object, or :class:`~psrqpy.pulsar.Pulsars`
+                object 
         """
 
         assert isinstance(psr, Pulsar) or isinstance(psr, Pulsars), 'psr is not a Pulsar type'
@@ -325,7 +332,8 @@ def remove_pulsar(self, psrname):
         """
         Remove a pulsar from the object. Only do one at a time.
 
-        :param psrname: a string with the name of a pulsar
+        Args:
+            psrname (str): a string with the name of a pulsar
         """
 
         assert isinstance(psrname, basestring), 'psrname is not a string'
@@ -337,7 +345,8 @@ def pop(self, psrname):
         """
         Remove a pulsar from the object and return the removed pulsar.
 
-        :param psrname: a string with the name of a pulsar
+        Args:
+            psrname (str): a string with the name of a pulsar
         """
         assert isinstance(psrname, basestring), 'psrname is not a string'
 
@@ -358,7 +367,10 @@ def have_ephemerides(self):
 
     def get_ephemerides(self, version=None):
         """
-        Query the ATNF to get the ephemerides for all pulsars in the object
+        Query the ATNF to get the ephemerides for all pulsars in the object.
+
+        Args:
+            version (str): the ATNF pulsar catalogue version to use.
         """
 
         if not self.have_ephemerides():

psrqpy/search.py

@@ -182,8 +182,7 @@ def generate_query(self, version='', params=None, condition='', sortorder='asc',
 
         Args:
             version (str): a string containing the ATNF version.
-            params (list, str): a list of `parameters
-                <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html#par_list>`_ to
+            params (list, str): a list of `parameters <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html#par_list>`_ to
                 query.
             condition (str): the logical `condition
                 <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html#condition>`_
@@ -788,19 +787,16 @@ def ppdot(self, intrinsicpdot=False, excludeGCs=False, showtypes=[], showGCs=Fal
             return None
 
         # set plot parameters
-        if not rcparams:
-            # set default parameters
-            rcparams = {
-                'figure.figsize': (10, 12),
-                'figure.dpi': 250,
-                'text.usetex': True,    # use LaTeX for all text
-                'axes.linewidth': 0.5,  # set axes linewidths to 0.5
-                'axes.grid': False,     # add a grid
-                'font.family': 'sans-serif',
-                'font.sans-serif': 'Avant Garde, Helvetica, Computer Modern Sans serif',
-                'font.size': 18,
-                'legend.fontsize': 'medium',
-                'legend.frameon': False}
+        rcparams['figure.figsize'] = rcparams['figure.figsize'] if 'figure.figsize' in rcparams else (9, 9.5)
+        rcparams['figure.dpi'] = rcparams['figure.dpi'] if 'figure.dpi' in rcparams else 250
+        rcparams['text.usetex'] = rcparams['text.usetex'] if 'text.usetex' in rcparams else True
+        rcparams['axes.linewidth'] = rcparams['axes.linewidth'] if 'axes.linewidth' in rcparams else 0.5
+        rcparams['axes.grid'] = rcparams['axes.grid'] if 'axes.grid' in rcparams else False
+        rcparams['font.family'] = rcparams['font.family'] if 'font.family' in rcparams else 'sans-serif'
+        rcparams['font.sans-serif'] = rcparams['font.sans-serif'] if 'font.sans-serif' in rcparams else 'Avant Garde, Helvetica, Computer Modern Sans serif'
+        rcparams['font.size'] = rcparams['font.size'] if 'font.size' in rcparams else 20
+        rcparams['legend.fontsize'] = rcparams['legend.fontsize'] if 'legend.fontsize' in rcparams else 16
+        rcparams['legend.frameon'] = rcparams['legend.frameon'] if 'legend.frameon' in rcparams else False
 
         mpl.rcParams.update(rcparams)
 

psrqpy/utils.py

@@ -47,7 +47,12 @@ def get_references(useads=False):
     Return a dictionary of paper reference in the ATNF catalogue. The keys are the ref strings given
     in the ATNF catalogue.
 
-    :param useads: boolean to set whether to use the python 'ads' module to get the NASA ADS URL for the references
+    Args:
+        useads (bool): boolean to set whether to use the python mod:`ads` module to get
+            the NASA ADS URL for the references
+
+    Returns:
+        dict: a dictionary of references.
     """
 
     refs = {}
@@ -238,12 +243,19 @@ def get_references(useads=False):
 def characteristic_age(period, pdot, braking_idx=3.):
     """
     Function defining the characteristic age of a pulsar. Returns the characteristic
-    age in years
+    age in using
 
+    .. math::
+    
+       \\tau = \\frac{P}{\dot{P}(n-1)}
+
+    Args:
+        period (float): the pulsar period in seconds
+        pdot (float): the pulsar period derivative
+        braking_idx (float): the pulsar braking index (defaults to :math:`n=3`)
 
-    :param period: the pulsar period in seconds
-    :param pdot: the pulsar period derivative
-    :param braking_idx: the pulsar braking index (defaults to n=3)
+    Returns:
+        float: the characteristic age in years
     """
 
     # check everything is positive, otherwise return NaN
@@ -265,11 +277,19 @@ def characteristic_age(period, pdot, braking_idx=3.):
 def age_pdot(period, tau=1e6, braking_idx=3.):
     """
     Function returning the period derivative for a pulsar with a given period
-    and characteristic age
+    and characteristic age, using
+
+    .. math::
+
+       \dot{P} = \\frac{\dot{P}}{\\tau(n - 1)}
+
+    Args:
+        period (list, :class:`numpy.ndarray`): the pulsar period in seconds
+        tau (float): the characteristic age in years
+        braking_idx (float): the pulsar braking index (defaults to :math:`n=3`)
 
-    :param period: the pulsar period in seconds
-    :param tau: the characteristic age in years
-    :param braking_idx: the pulsar braking index (defaults to n=3)
+    Returns:
+        :class:`numpy.ndarray`: an array of period derivatives.
     """
 
     periods = period
@@ -287,7 +307,18 @@ def age_pdot(period, tau=1e6, braking_idx=3.):
 def B_field(period, pdot):
     """
     Function defining the polar magnetic field strength at the surface of the pulsar
-    in gauss (Eqn 5.12 of Lyne & Graham-Smith, Pulsar Astronmy, 2nd edition)
+    in gauss (Equation 5.12 of Lyne & Graham-Smith, Pulsar Astronmy, 2nd edition) with
+    
+    .. math::
+
+       B = 3.2\!\\times\!10^{19} \\sqrt{P\dot{P}}
+
+    Args:
+        period (float): a pulsar period (s)
+        pdot (float): a period derivative
+
+    Returns:
+        float: the magnetic field strength in gauss.
     """
 
     assert isinstance(period, float) or isinstance(period, int), "Period '{}' must be a number".format(period)
@@ -308,7 +339,18 @@ def B_field(period, pdot):
 def B_field_pdot(period, Bfield=1e10):
     """
     Function to get the period derivative from a given pulsar period and magnetic
-    field strength
+    field strength using
+    
+    .. math::
+    
+       \dot{P} = \\frac{1}{P}\left( \\frac{B}{3.2\!\\times\!10^{19}} \\right)^2
+
+    Args:
+        period (list, :class:`~numpy.ndarray`): a list of period values
+        Bfield (float): the polar magnetic field strength (Defaults to :math:`10^{10}` G)
+        
+    Returns:
+        :class:`numpy.ndarray`: an array of period derivatives
     """
 
     periods = period
@@ -379,7 +421,7 @@ def label_line(ax, line, label, color='k', fs=14, frachoffset=0.1):
         color (str): a color string for the label text. Defaults to ``'k'``
         fs (int): the font size for the label text. Defaults to 14.
         frachoffset (float): a number between 0 and 1 giving the fractional offset of the label
-           text along the x-axis. Defaults to 0.1, i.e. 10%.
+            text along the x-axis. Defaults to 0.1, i.e. 10%.
 
     Returns:
         :class:`matplotlib.text.Text`: a :class:`~matplotlib.text.Text` object containing the label

setup.py

@@ -29,6 +29,13 @@ def readfile(filename):
 
 VERSION = VERSION_REGEX.findall(CONTENTS)[0]
 
+# 'setup.py publish' shortcut for publishing (e.g. setup.py from requests https://github.com/requests/requests/blob/master/setup.py)
+# 'setup.py publish' shortcut.
+if sys.argv[-1] == 'publish':
+    os.system('python setup.py sdist bdist_wheel --universal')
+    os.system('twine upload dist/*')
+    sys.exit()
+
 setup(name="psrqpy",
       version=VERSION,
       author="Matthew Pitkin",