Minor documentation updates

docs/source/index.rst

@@ -71,6 +71,13 @@ The number of pulsars can easily be accessed, e.g.,
 The code will automatically attempt to query the current version of the
 ATNF catalogue, the value of which is printed in the above example.
 
+.. note::
+
+   If you really want to query the catalogue many times in quick succession it is advisable not to use this module, as
+   it could result in too much load on the ATNF catalogue's server. Instead it is probably preferable to `download
+   the catalogue <http://www.atnf.csiro.au/research/pulsar/psrcat/download.html>`_ and query it with the ``psrcat`` software
+   provided.
+
 More complex queries
 --------------------
 

psrqpy/pulsar.py

@@ -264,7 +264,7 @@ def __copy__(self):
 
 class Pulsars(object):
     """
-    Class to contain multiple Pulsar objects
+    Class to contain multiple :class:`~psrqpy.pulsar.Pulsar` objects.
     """
 
     def __init__(self):

psrqpy/search.py

@@ -53,7 +53,9 @@ class QueryATNF(object):
         psrs (:obj:`list`): a list of pulsar names for which to get the requested parameters.
             Defaults to None.
         include_errs (bool): Set if wanting parameter errors to be returned. Defaults to True.
-        include_refs (bool): Set if wanting parameter references to be returned. Defaults to False.
+        include_refs (bool): Set if wanting parameter
+            `references <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_ref.html>`_ to be
+            returned. Defaults to False.
         get_ephemeris (bool): Set if wanting to get pulsar ephemerides (only works if `psrs` have
             been specified). Defaults to False.
         version (str): a string with the ATNF version to use (this will default to the current
@@ -729,11 +731,12 @@ def ppdot(self, intrinsicpdot=False, excludeGCs=False, showtypes=[], showGCs=Fal
             showB (bool): show lines of constant magnetic field strength. Defaults to True, and
                 shows lines for :math:`10^{10}` through to :math:`10^{14}` gauss with steps in
                 powers of 10.
-            Bfield (:py:obj:`list`): a list of magnetic field strengths to plot.
-            rcparams (dict): a dictionary of :py:obj:`matplotlib.rcParams` setup parameters for the plot.
+            Bfield (list): a list of magnetic field strengths to plot.
+            rcparams (dict): a dictionary of :py:obj:`matplotlib.rcParams` setup parameters for the
+                plot.
 
         Returns:
-            A :class:`matplotlib.figure.Figure` object
+            :class:`matplotlib.figure.Figure`: the figure object
         """
 
         try:

psrqpy/utils.py

@@ -44,8 +44,9 @@ def get_version():
 
 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.
+    Return a dictionary of paper
+    `reference <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_ref.html>`_ in the ATNF
+    catalogue. The keys are the ref strings given in the ATNF catalogue.
 
     Args:
         useads (bool): boolean to set whether to use the python mod:`ads` module to get
@@ -423,9 +424,9 @@ def label_line(ax, line, label, color='k', fs=14, frachoffset=0.1):
         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%.
 
+
     Returns:
-        :class:`matplotlib.text.Text`: a :class:`~matplotlib.text.Text` object containing the label
-            information
+        :class:`matplotlib.text.Text`: an object containing the label information
 
     """
     xdata, ydata = line.get_data()