docs: Fix all sphinx warnings

...and also enforce a warning-free build within the CI.

Change-Id: Ia406a0a1ca2e89ceaa0288ae82128fa9427fe066

.travis.yml

@@ -14,7 +14,7 @@ script:
   - ./examples/transmission_main_example.py
   - ./examples/path_requests_run.py
   - ./examples/transmission_main_example.py examples/raman_edfa_example_network.json --sim examples/sim_params.json --show-channels
-  - sphinx-build docs/ x-throwaway-location
+  - sphinx-build -W --keep-going docs/ x-throwaway-location
 after_success:
   - bash <(curl -s https://codecov.io/bash)
 jobs:

docs/conf.py

@@ -166,4 +166,9 @@ texinfo_documents = [
      'Miscellaneous'),
 ]
 
-autodoc_default_flags = ['members', 'undoc-members', 'private-members', 'show-inheritance']
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': True,
+    'private-members': True,
+    'show-inheritance': True,
+}

docs/source/modules.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 gnpy
 ====
 

gnpy/core/elements.py

@@ -548,8 +548,6 @@ class Edfa(Node):
 
     def interpol_params(self, frequencies, pin, baud_rates, pref):
         """interpolate SI channel frequencies with the edfa dgt and gain_ripple frquencies from JSON
-        set the edfa class __init__ None parameters :
-                self.channel_freq, self.nf, self.interpol_dgt and self.interpol_gain_ripple
         """
         # TODO|jla: read amplifier actual frequencies from additional params in json
         amplifier_freq = arrange_frequencies(len(self.params.dgt), self.params.f_min, self.params.f_max) # Hz
@@ -646,8 +644,9 @@ class Edfa(Node):
             return self.interpol_nf_ripple + nf_avg # input VOA = 1 for 1 NF degradation
 
     def noise_profile(self, df):
-        """noise_profile(bw) computes amplifier ase (W) in signal bw (Hz)
-        noise is calculated at amplifier input
+        """noise_profile(bw) computes amplifier ASE (W) in signal bandwidth (Hz)
+
+        Noise is calculated at amplifier input
 
         :bw: signal bandwidth = baud rate in Hz
         :type bw: float
@@ -655,8 +654,8 @@ class Edfa(Node):
         :return: the asepower in W in the signal bandwidth bw for 96 channels
         :return type: numpy array of float
 
-        ASE POWER USING PER CHANNEL GAIN PROFILE
-        INPUTS:
+        ASE power using per channel gain profile inputs:
+
             NF_dB - Noise figure in dB, vector of length number of channels or
                     spectral slices
             G_dB  - Actual gain calculated for the EDFA, vector of length number of
@@ -665,9 +664,14 @@ class Edfa(Node):
                     THz, vector of length number of channels or spectral slices
             dF    - width of each channel or spectral slice in THz,
                     vector of length number of channels or spectral slices
+
         OUTPUT:
+
             ase_dBm - ase in dBm per channel or spectral slice
-        NOTE: the output is the total ASE in the channel or spectral slice. For
+
+        NOTE:
+
+            The output is the total ASE in the channel or spectral slice. For
             50GHz channels the ASE BW is effectively 0.4nm. To get to noise power
             in 0.1nm, subtract 6dB.
 
@@ -691,36 +695,26 @@ class Edfa(Node):
         :param gain_ripple: design flat gain
         :param dgt: design gain tilt
         :param Pin: total input power in W
-        :param gp: Average gain setpoint in dB units
-        :param gtp: gain tilt setting
+        :param gp: Average gain setpoint in dB units (provisioned gain)
+        :param gtp: gain tilt setting (provisioned tilt)
         :type gain_ripple: numpy.ndarray
         :type dgt: numpy.ndarray
         :type Pin: numpy.ndarray
         :type gp: float
         :type gtp: float
-        :return: gain profile in dBm
+        :return: gain profile in dBm, per channel or spectral slice
         :rtype: numpy.ndarray
 
-        AMPLIFICATION USING INPUT PROFILE
-        INPUTS:
-            gain_ripple - vector of length number of channels or spectral slices
-            DGT - vector of length number of channels or spectral slices
-            Pin - input powers vector of length number of channels or
-            spectral slices
-            Gp  - provisioned gain length 1
-            GTp - provisioned tilt length 1
+        Checking of output power clamping is implemented in interpol_params().
+
 
-        OUTPUT:
-            amp gain per channel or spectral slice
-        NOTE: there is no checking done for violations of the total output
-            power capability of the amp.
-        EDIT OF PREVIOUS NOTE: power violation now added in interpol_params
-            Ported from Matlab version written by David Boerges at Ciena.
         Based on:
+
             R. di Muro, "The Er3+ fiber gain coefficient derived from a dynamic
-            gain
-            tilt technique", Journal of Lightwave Technology, Vol. 18, Iss. 3,
-            Pp. 343-347, 2000.
+            gain tilt technique", Journal of Lightwave Technology, Vol. 18,
+            Iss. 3, Pp. 343-347, 2000.
+
+            Ported from Matlab version written by David Boerges at Ciena.
         """
 
         # TODO|jla: check what param should be used (currently length(dgt))

gnpy/core/utils.py

@@ -29,8 +29,8 @@ def save_json(obj, filename):
 
 def write_csv(obj, filename):
     """
-    convert dictionary items to a csv file
-    the dictionary format :
+    Convert dictionary items to a CSV file the dictionary format:
+    ::
 
         {'result category 1':
                         [
@@ -47,7 +47,9 @@ def write_csv(obj, filename):
                         ]
         }
 
-    the generated csv file will be:
+    The generated csv file will be:
+    ::
+
         result_category 1
         header 1    header 2
         value_xxx   value_yyy
@@ -77,12 +79,12 @@ def arrange_frequencies(length, start, stop):
     """Create an array of frequencies
 
     :param length: number of elements
-    :param star: Start frequency in THz
+    :param start: Start frequency in THz
     :param stop: Stop frequency in THz
     :type length: integer
     :type start: float
     :type stop: float
-    :return an array of frequencies determined by the spacing parameter
+    :return: an array of frequencies determined by the spacing parameter
     :rtype: numpy.ndarray
     """
     return np.linspace(start, stop, length)

tox.ini

@@ -18,5 +18,5 @@ deps =
 	-r{toxinidir}/requirements.txt
 	rstcheck
 commands =
-	sphinx-build -E -q -b html docs/ doc/build/html
+	sphinx-build -E -W --keep-going -q -b html docs/ doc/build/html
 	rstcheck --ignore-roles cite --ignore-directives automodule --recursive --ignore-messages '(Duplicate explicit target name.*)' {toxinidir}