Merge pull request #256 from jktjkt/docs

Documentation fixes (plus an equipment.Fiber.beta2 change)

docs/conf.py

@@ -173,5 +173,4 @@ texinfo_documents = [
      'Miscellaneous'),
 ]
 
-
+autodoc_default_flags = ['members', 'undoc-members', 'private-members', 'show-inheritance']
-

docs/source/gnpy.core.rst

@@ -4,10 +4,39 @@ gnpy\.core package
 Submodules
 ----------
 
+gnpy\.core\.ansi_escapes module
+-------------------------------
+
+.. automodule:: gnpy.core.ansi_escapes
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+gnpy\.core\.convert module
+--------------------------
+
+.. automodule:: gnpy.core.convert
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 gnpy\.core\.elements module
 ---------------------------
 
 .. automodule:: gnpy.core.elements
+
+gnpy\.core\.equipment module
+----------------------------
+
+.. automodule:: gnpy.core.equipment
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+gnpy\.core\.exceptions module
+-----------------------------
+
+.. automodule:: gnpy.core.exceptions
     :members:
     :undoc-members:
     :show-inheritance:
@@ -16,30 +45,34 @@ gnpy\.core\.execute module
 --------------------------
 
 .. automodule:: gnpy.core.execute
-    :members:
-    :undoc-members:
-    :show-inheritance:
 
 gnpy\.core\.info module
 -----------------------
 
 .. automodule:: gnpy.core.info
-    :members:
-    :undoc-members:
-    :show-inheritance:
 
 gnpy\.core\.network module
 --------------------------
 
 .. automodule:: gnpy.core.network
-    :members:
-    :undoc-members:
-    :show-inheritance:
 
 gnpy\.core\.node module
 -----------------------
 
 .. automodule:: gnpy.core.node
+
+gnpy\.core\.request module
+--------------------------
+
+.. automodule:: gnpy.core.request
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+gnpy\.core\.service_sheet module
+--------------------------------
+
+.. automodule:: gnpy.core.service_sheet
     :members:
     :undoc-members:
     :show-inheritance:
@@ -48,23 +81,14 @@ gnpy\.core\.units module
 ------------------------
 
 .. automodule:: gnpy.core.units
-    :members:
-    :undoc-members:
-    :show-inheritance:
 
 gnpy\.core\.utils module
 ------------------------
 
 .. automodule:: gnpy.core.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:
 
 
 Module contents
 ---------------
 
 .. automodule:: gnpy.core
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/gnpy.rst

@@ -12,6 +12,3 @@ Module contents
 ---------------
 
 .. automodule:: gnpy
-    :members:
-    :undoc-members:
-    :show-inheritance:

gnpy/core/elements.py

@@ -7,11 +7,11 @@ gnpy.core.elements
 
 This module contains standard network elements.
 
-A network element is a Python callable. It takes a .info.SpectralInformation
+A network element is a Python callable. It takes a :class:`.info.SpectralInformation`
 object and returns a copy with appropriate fields affected. This structure
 represents spectral information that is "propogated" by this network element.
 Network elements must have only a local "view" of the network and propogate
-SpectralInformation using only this information. They should be independent and
+:class:`.info.SpectralInformation` using only this information. They should be independent and
 self-contained.
 
 Network elements MUST implement two attributes .uid and .name representing a
@@ -290,12 +290,12 @@ class Fiber(Node):
 
     @property
     def fiber_loss(self):
-        # dB fiber loss, not including padding attenuator
+        """Fiber loss in dB, not including padding attenuator"""
         return self.loss_coef * self.length + self.con_in + self.con_out
 
     @property
     def loss(self):
-        #total loss incluiding padding att_in: useful for polymorphism with roadm loss
+        """total loss including padding att_in: useful for polymorphism with roadm loss"""
         return self.loss_coef * self.length + self.con_in + self.con_out + self.att_in
 
     @property
@@ -320,8 +320,10 @@ class Fiber(Node):
 
     def carriers(self, loc, attr):
         """retrieve carriers information
-        loc = (in, out) of the class element
+
-        attr = (ase, nli, signal, total) power information"""
+        :param loc: (in, out) of the class element
+        :param attr: (ase, nli, signal, total) power information
+        """
         if not (loc in ('in', 'out') and attr in ('nli', 'signal', 'total', 'ase')):
             yield None
             return
@@ -337,31 +339,28 @@ class Fiber(Node):
             else:
                 yield c.power._asdict().get(attr, None)
 
-    def beta2(self, ref_wavelength=None):
+    def beta2(self, ref_wavelength=1550e-9):
-        """ Returns beta2 from dispersion parameter.
+        """Returns beta2 from dispersion parameter.
         Dispersion is entered in ps/nm/km.
-        Disperion can be a numpy array or a single value.  If a
+        Disperion can be a numpy array or a single value.
-        value ref_wavelength is not entered 1550e-9m will be assumed.
+
-        ref_wavelength can be a numpy array.
+        :param ref_wavelength: can be a numpy array; default: 1550nm
         """
         # TODO|jla: discuss beta2 as method or attribute
-        wl = 1550e-9 if ref_wavelength is None else ref_wavelength
         D = abs(self.dispersion)
-        b2 = (wl ** 2) * D / (2 * pi * c)  # 10^21 scales [ps^2/km]
+        b2 = (ref_wavelength ** 2) * D / (2 * pi * c)  # 10^21 scales [ps^2/km]
         return b2 # s/Hz/m
 
     def dbkm_2_lin(self):
-        """ calculates the linear loss coefficient
+        """calculates the linear loss coefficient"""
-        """
+        # linear loss coefficient in dB/km^-1
-        # alpha_pcoef is linear loss coefficient in dB/km^-1
-        # alpha_acoef is linear loss field amplitude coefficient in m^-1
         alpha_pcoef = self.loss_coef
+        # linear loss field amplitude coefficient in m^-1
         alpha_acoef = alpha_pcoef / (2 * 10 * log10(exp(1)))
         return alpha_pcoef, alpha_acoef
 
     def _psi(self, carrier, interfering_carrier):
-        """ Calculates eq. 123 from	arXiv:1209.0394.
+        """Calculates eq. 123 from `arXiv:1209.0394 <https://arxiv.org/abs/1209.0394>`__"""
-        """
         if carrier.num_chan == interfering_carrier.num_chan: # SCI
             psi = arcsinh(0.5 * pi**2 * self.asymptotic_length
                               * abs(self.beta2()) * carrier.baud_rate**2)
@@ -375,8 +374,9 @@ class Fiber(Node):
         return psi
 
     def _gn_analytic(self, carrier, *carriers):
-        """ Computes the nonlinear interference power on a single carrier.
+        """Computes the nonlinear interference power on a single carrier.
-        The method uses eq. 120 from arXiv:1209.0394.
+        The method uses eq. 120 from `arXiv:1209.0394 <https://arxiv.org/abs/1209.0394>`__.
+
         :param carrier: the signal under analysis
         :param carriers: the full WDM comb
         :return: carrier_nli: the amount of nonlinear interference in W on the under analysis
@@ -557,8 +557,10 @@ class Edfa(Node):
 
     def carriers(self, loc, attr):
         """retrieve carriers information
-        loc = (in, out) of the class element
+
-        attr = (ase, nli, signal, total) power information"""
+        :param loc: (in, out) of the class element
+        :param attr: (ase, nli, signal, total) power information
+        """
         if not (loc in ('in', 'out') and attr in ('nli', 'signal', 'total', 'ase')):
             yield None
             return
@@ -575,7 +577,7 @@ class Edfa(Node):
                 yield c.power._asdict().get(attr, None)
 
     def interpol_params(self, frequencies, pin, baud_rates, pref):
-        """interpolate SI channel frequencies with the edfa dgt and gain_ripple frquencies from json
+        """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
         """
@@ -674,7 +676,7 @@ 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_profile(bw) computes amplifier ase (W) in signal bw (Hz)
         noise is calculated at amplifier input
 
         :bw: signal bandwidth = baud rate in Hz
@@ -829,7 +831,7 @@ class Edfa(Node):
         return g1st - voa + array(self.interpol_dgt) * dgts3
 
     def propagate(self, pref, *carriers):
-        """add ase noise to the propagating carriers of SpectralInformation"""
+        """add ASE noise to the propagating carriers of :class:`.info.SpectralInformation`"""
         pin = array([c.power.signal+c.power.nli+c.power.ase for c in carriers]) # pin in W
         freq = array([c.frequency for c in carriers])
         brate = array([c.baud_rate for c in carriers])

gnpy/core/info.py

@@ -5,7 +5,7 @@
 gnpy.core.info
 ==============
 
-This module contains classes for modelling SpectralInformation.
+This module contains classes for modelling :class:`SpectralInformation`.
 '''
 
 

gnpy/core/node.py

@@ -8,13 +8,13 @@ gnpy.core.node
 This module contains the base class for a network element.
 
 Strictly, a network element is any callable which accepts an immutable
-.info.SpectralInformation object and returns a .info.SpectralInformation object
+:class:`.info.SpectralInformation` object and returns an :class:`.info.SpectralInformation` object
-(a copy.)
+(a copy).
 
 Network elements MUST implement two attributes .uid and .name representing a
 unique identifier and a printable name.
 
-This base class provides a mode convenient way to define a network element
+This base class provides a more convenient way to define a network element
 via subclassing.
 '''