Fixing docstrings & indentation related warnings for Sphinx (#1617)

docs/development/matterbridge.rst

@@ -9,7 +9,9 @@ Overview
 We use Matterbridge to connect channels across different messaging platforms
 such as *Slack*, *Mattermost* and *Gitter*. Matterbridge provides binaries 
 for  many operating systems. The ``matterbridge`` binary is intended to be used
-in combination with a TOML configuration file::
+in combination with a TOML configuration file:
+::
+
   $ ./matterbridge -conf config-tardis-matterbridge.toml
 
 The TOML file includes all the parameters required to connect as many
@@ -91,7 +93,7 @@ After updating the TOML file, follow these steps:
 ========
 Cron job
 ========
- 
+
 To edit the cron job, *ssh* to `OpenSupernova.org`_ and run ``sudo crontab -e``.
 
 

docs/installation.rst

@@ -14,11 +14,12 @@ installed TARDIS, check out the "Using TARDIS" section (in sidebar) for instruct
 
 
 .. note::
-        
+
     - TARDIS is only compatible with Python >=3.6
     - TARDIS only supports Linux and MacOS.
     - We strongly recommend installing TARDIS within an Anaconda environment and to always use the latest GitHub development version.
 
+
 Requirements
 ============
 
@@ -40,25 +41,30 @@ where ``root``-rights are not available. Use these `instructions
 <http://docs.continuum.io/anaconda/install.html>`_ to install Anaconda on your
 machine. The next step is to create an environment for TARDIS that contains all
 of the necessary packages (this ensures that TARDIS requirements won't clash
-with any other Python installs on disc)::
+with any other Python installs on disc):
 
-First, download the `environment definition file <https://raw.githubusercontent.com/tardis-sn/tardis/master/tardis_env3.yml>`_ from::
+First, download the `environment definition file <https://raw.githubusercontent.com/tardis-sn/tardis/master/tardis_env3.yml>`_ from:
+::
 
     https://raw.githubusercontent.com/tardis-sn/tardis/master/tardis_env3.yml
 
-To create the environment, change to the directory that you downloaded the environment definition file and run::
+To create the environment, change to the directory that you downloaded the environment definition file and run:
+::
 
     conda env create -f tardis_env3.yml
 
-Then to activate this environment simply do::
+Then to activate this environment simply do:
+::
 
     source activate tardis
 
-or the new method::
+or the new method:
+::
 
     conda activate tardis
 
-and after you are done with TARDIS you can deactivate::
+and after you are done with TARDIS you can deactivate:
+::
 
     source deactivate
 
@@ -71,7 +77,8 @@ until the step to install TARDIS in the development mode
 TARDIS can be found `here <https://tardis-sn.github.io/tardis/development/index.html>`_.
 
 To install TARDIS, it is recommended to first clone our repository and
-then install TARDIS, as follows::
+then install TARDIS, as follows:
+::
 
     git clone https://github.com/tardis-sn/tardis.git
     cd tardis
@@ -88,7 +95,8 @@ method because this often fixes problems. Here are some common problems when
 installing and their fixes:
 
 **Problem:** While building TARDIS via ``python setup.py`` build you
-may encounter the following error::
+may encounter the following error:
+::
 
     error: tardis/montecarlo/montecarlo.c: Could not find C file tardis/montecarlo/montecarlo.c for Cython file tardis/montecarlo/montecarlo.pyx when building extension tardis.montecarlo.montecarlo. Cython must be installed to build from a git checkout.
 
@@ -98,7 +106,8 @@ help. To clean up your repository please try ``python setup.py clean`` and
 then ``git clean -dfx`` (**WARNING** will delete any non-TARDIS file in that directory)
 This will often clean this problem. If it still persists:
 
-Go into the tardis/montecarlo directory and build montecarlo.c by hand::
+Go into the tardis/montecarlo directory and build montecarlo.c by hand:
+::
 
     cython montecarlo.pyx
 
@@ -107,31 +116,36 @@ Then, ``python setup.py build`` should run without problems.
 
 **Problem:** when trying to set up CC=gcc python setup.py develop --with-openmp the following error popped up: 
 from tardis/_compiler.c:1: /Users/yssavo/miniconda2/envs/tardis-show2/lib/gcc/x86_64-apple-darwin13.4.0/5.2.0/include-fixed/limits.h:168:61: fatal error: limits.h: No such file or directory 
-        
+
 **Solution:** Run on terminal: 
+::
 
     open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg
 
 **Problem:** Symbol not found: _GOMP_parallel when compiling with `--with-openmp`
 
-**Solution:** Install gcc8 from macports and then install with these flags: `link_args = ['-fopenmp','-Wl,-rpath,/opt/local/lib/gcc8/']`
+**Solution:** Install gcc8 from macports and then install with these flags: ``link_args = ['-fopenmp','-Wl,-rpath,/opt/local/lib/gcc8/']``
 
 **Problem:** While building TARDIS (via python 2.7) via ``python setup.py`` build you
-may encounter the following error::
+may encounter the following error:
+::
 
-     TypeError: super() argument 1 must be type, not None
+    TypeError: super() argument 1 must be type, not None
     
     ----------------------------------------
     Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-req-build-wPB39p/
 
 
 **Solution:** The cause for this problem is Sphinx or Sphinx version. It can be easily solved by installing Sphinx 1.5.6.
-              The command for the same is :
+The command for the same is :
+::
 
     pip install sphinx==1.5.6
-
-    or
-
+
+or
+
+::
+
     conda install sphinx==1.5.6
 
 Then, ``python setup.py build install`` should run without problems.

docs/using/components/atomic/atomic_data_description.rst

@@ -53,11 +53,11 @@ Ionization Data
 
 
 .. note:: In TARDIS, Ion 0 is neutral. 
-The levels data is stored in ``levels_data``.
+
 
 Levels Data
 ^^^^^^^^^^^
-
+The levels data is stored in ``levels_data``.
 
 +------------------------+------------------------------+----------+
 |Name                    | Description                  | Unit     |
@@ -129,8 +129,8 @@ has three states:
 
 * -1 for downwards emitting
 * 0 for downwards internal
-* 1 for upwards internal (for more explanations, please
-refer to :ref:`macroatom`).
+* 1 for upwards internal (for more explanations, please refer to :ref:`macroatom`).
+
 
 Macro Atom Data
 ^^^^^^^^^^^^^^^

tardis/io/atom_data/base.py

@@ -31,57 +31,67 @@ class AtomData(object):
     Parameters
     ----------
     atom_data : pandas.DataFrame
-        A DataFrame containing the *basic atomic data* with:
-            index : atomic_number;
-            columns : symbol, name, mass[u].
+    A DataFrame containing the *basic atomic data* with:
+        index : atomic_number
+        columns : symbol, name, mass[u].
+
     ionization_data : pandas.DataFrame
-        A DataFrame containing the *ionization data* with:
-            index : atomic_number, ion_number;
-            columns : ionization_energy[eV].
-        It is important to note here is that `ion_number` describes the *final ion state*
-            e.g. H I - H II is described with ion=1
+    A DataFrame containing the *ionization data* with:
+        index : atomic_number, ion_number
+        columns : ionization_energy[eV].
+    It is important to note here is that `ion_number` describes the *final ion state*
+    e.g. H I - H II is described with ion=1
+
     levels : pandas.DataFrame
-        A DataFrame containing the *levels data* with:
-            index : numerical index;
-            columns : atomic_number, ion_number, level_number, energy[eV], g[1], metastable.
+    A DataFrame containing the *levels data* with:
+        index : numerical index
+        columns : atomic_number, ion_number, level_number, energy[eV], g[1], metastable.
+
     lines : pandas.DataFrame
-        A DataFrame containing the *lines data* with:
-            index : numerical index;
-            columns : line_id, atomic_number, ion_number, level_number_lower, level_number_upper,
-                wavelength[angstrom], nu[Hz], f_lu[1], f_ul[1], B_ul[?], B_ul[?], A_ul[1/s].
+    A DataFrame containing the *lines data* with:
+        index : numerical index
+        columns : line_id, atomic_number, ion_number, level_number_lower, level_number_upper,
+        wavelength[angstrom], nu[Hz], f_lu[1], f_ul[1], B_ul[?], B_ul[?], A_ul[1/s].
+
     macro_atom_data :
-        A DataFrame containing the *macro atom data* with:
-            index : numerical index;
-            columns : atomic_number, ion_number, source_level_number, destination_level_number,
-                transition_line_id, transition_type, transition_probability;
+    A DataFrame containing the *macro atom data* with:
+        index : numerical index
+        columns : atomic_number, ion_number, source_level_number, destination_level_number,
+        transition_line_id, transition_type, transition_probability;
+
     macro_atom_references :
-        A DataFrame containing  the *macro atom references* with:
-            index : numerical index;
-            columns : atomic_number, ion_number, source_level_number, count_down, count_up, count_total.
-        Refer to the docs: http://tardis.readthedocs.io/en/latest/physics/plasma/macroatom.html
+    A DataFrame containing  the *macro atom references* with:
+        index : numerical index
+        columns : atomic_number, ion_number, source_level_number, count_down, count_up, count_total.
+    Refer to the docs: http://tardis.readthedocs.io/en/latest/physics/plasma/macroatom.html
+
     collision_data : (pandas.DataFrame, np.array)
-        A DataFrame containing the *electron collisions data* with:
-            index : atomic_number, ion_number, level_number_lower, level_number_upper;
-            columns : e_col_id, delta_e, g_ratio, c_ul;
+    A DataFrame containing the *electron collisions data* with:
+        index : atomic_number, ion_number, level_number_lower, level_number_upper
+        columns : e_col_id, delta_e, g_ratio, c_ul;
+
     collision_data_temperatures : np.array
         An array with the collision temperatures.
+
     zeta_data :
-        A DataFrame containing the *zeta data* for the
-        nebular ionization calculation
-        (i.e., the fraction of recombinations that go directly to the
-        ground state) with:
-            index : atomic_number, ion_charge;
-            columns : temperatures[K]
+    A DataFrame containing the *zeta data* for the
+    nebular ionization calculation
+    (i.e., the fraction of recombinations that go directly to the
+    ground state) with:
+        index : atomic_number, ion_charge
+        columns : temperatures[K]
+
     synpp_refs : ?
+
     photoionization_data : pandas.DataFrame
-        A DataFrame containing the *photoionization data* with:
-            index : numerical index;
-            columns : atomic_number, ion_number, level_number, nu[Hz], x_sect[cm^2]
+    A DataFrame containing the *photoionization data* with:
+        index : numerical index
+        columns : atomic_number, ion_number, level_number, nu[Hz], x_sect[cm^2]
 
     two_photon_data : pandas.DataFrame
-        A DataFrame containing the *two photon decay data* with:
-            index: atomic_number, ion_number, level_number_lower, level_number_upper
-            columns: A_ul[1/s], nu0[Hz], alpha, beta, gamma
+    A DataFrame containing the *two photon decay data* with:
+        index: atomic_number, ion_number, level_number_lower, level_number_upper
+        columns: A_ul[1/s], nu0[Hz], alpha, beta, gamma
 
     Attributes
     ----------

tardis/montecarlo/packet_source.py

@@ -48,8 +48,7 @@ def create_uniform_packet_energies(no_of_packets, rng):
 
         Returns
         -------
-            : numpy.ndarray
-            energies for packets
+            energies for packets : numpy.ndarray
         """
         return np.ones(no_of_packets) / no_of_packets
 
@@ -62,16 +61,17 @@ def create_blackbody_packet_nus(T, no_of_packets, rng, l_samples=1000):
         First, generate a uniform random number, :math:`\\xi_0 \\in [0, 1]` and
         determine the minimum value of
         :math:`l, l_{\\rm min}`, that satisfies the condition
+
         .. math::
-            \\sum_{i=1}^{l} i^{-4} \\ge {{\\pi^4}\\over{90}} m_0 \\; .
+            \\sum_{i=1}^{l} i^{-4} \\ge {{\\pi^4}\\over{90}} m_0 \\;.
 
         Next obtain four additional uniform random numbers (in the range 0
         to 1) :math:`\\xi_1, \\xi_2, \\xi_3, {\\rm and } \\xi_4`.
-
         Finally, the packet frequency is given by
 
         .. math::
-            x = -\\ln{(\\xi_1\\xi_2\\xi_3\\xi_4)}/l_{\\rm min}\\; .
+            x = -\\ln{(\\xi_1\\xi_2\\xi_3\\xi_4)}/l_{\\rm min}\\;.
+
         where :math:`x=h\\nu/kT`
 
         Parameters
@@ -84,8 +84,7 @@ def create_blackbody_packet_nus(T, no_of_packets, rng, l_samples=1000):
 
         Returns
         -------
-            : numpy.ndarray
-            array of frequencies
+            array of frequencies: numpy.ndarray
         """
         l_samples = l_samples
         l_array = np.cumsum(np.arange(1, l_samples, dtype=np.float64) ** -4)

tardis/plasma/properties/atomic.py

@@ -201,11 +201,12 @@ def calculate(self, atomic_data, continuum_interaction_species):
 class TwoPhotonData(ProcessingPlasmaProperty):
     outputs = ("two_photon_data", "two_photon_idx")
     """
-    Attributes:
+    Attributes
+    ----------
     two_photon_data : pandas.DataFrame, dtype float
-        A DataFrame containing the *two photon decay data* with:
-            index: atomic_number, ion_number, level_number_lower, level_number_upper
-            columns: A_ul[1/s], nu0[Hz], alpha, beta, gamma
+    A DataFrame containing the *two photon decay data* with:
+        index: atomic_number, ion_number, level_number_lower, level_number_upper
+        columns: A_ul[1/s], nu0[Hz], alpha, beta, gamma
         alpha, beta, gamma are fit coefficients for the frequency dependent
         transition probability A(y) of the two photon decay. See Eq. 2 in
         Nussbaumer & Schmutz (1984).
@@ -281,9 +282,10 @@ def calculate(self, levels, lines):
 
 class LevelIdxs2LineIdx(HiddenPlasmaProperty):
     """
-    Attributes:
+    Attributes
+    ----------
     level_idxs2line_idx : pandas.Series, dtype int
-       Maps a source_level_idx destination_level_idx pair to a line_idx.
+        Maps a source_level_idx destination_level_idx pair to a line_idx.
     """
 
     outputs = ("level_idxs2line_idx",)

tardis/simulation/base.py

@@ -98,8 +98,8 @@ class Simulation(PlasmaStateStorerMixin, HDFWriterMixin):
     nthreads : int
         The number of threads to run montecarlo with
 
-        .. note:: TARDIS must be built with OpenMP support in order for
-        `nthreads` to have effect.
+        .. note:: TARDIS must be built with OpenMP support in order for ``nthreads`` to have effect.
+
     """
 
     hdf_properties = [