[Doc] Fix some Sphinx warnings

Comments are also added to note places where the function
signatures embedded by Cython produce warnings in Sphinx.
These warnings should be ignored until Sphinx supports this.

doc/sphinx/cti/input-files.rst

@@ -371,7 +371,7 @@ machines, and provide a preprocessor to convert the human-friendly format to the
 machine-friendly one.
 
 Preprocessor Internals: the ``ctml_writer`` Module
--------------------------------------------------
+--------------------------------------------------
 
 If you are interested in seeing the internals of how the preprocessing works,
 take a look at file ``ctml_writer.py`` in the Cantera Python package. Or simply

doc/sphinx/cti/phases.rst

@@ -257,9 +257,9 @@ The options field is used to indicate how certain conditions should be handled
 when importing the phase definition.  The options field may be assigned a string
 or a sequence of strings from the table below.
 
-==================================  ================
+==================================  ========================================================
 Option String                       Meaning
-==================================  ================
+==================================  ========================================================
 ``'skip_undeclared_elements'``      When importing species, skip any containing undeclared
                                     elements, rather than flagging them as an error.
 ``'skip_undeclared_species'``       When importing reactions, skip any containing undeclared
@@ -270,7 +270,7 @@ Option String                       Meaning
 ``'allow_discontinuous_thermo'``    Disable the automatic adjustment of NASA polynomials to
                                     eliminate discontinuities in enthalpy and entropy at the
                                     midpoint temperature.
-==================================  ================
+==================================  ========================================================
 
 Using the ``options`` field, it is possible to extract a sub-mechanism from a large
 reaction mechanism, as follows::

interfaces/cython/cantera/ctml_writer.py

@@ -256,11 +256,13 @@ def export_species(filename, fmt = 'CSV'):
 def validate(species = 'yes', reactions = 'yes'):
     """
     Enable or disable validation of species and reactions.
+
     :param species:
-        Set to 'yes' (default) or 'no'.
+        Set to ``'yes'`` (default) or ``'no'``.
     :param reactions:
-        Set to 'yes' (default) or 'no'. This controls duplicate reaction checks
+        Set to ``'yes'`` (default) or ``'no'``. This controls duplicate reaction checks
         and validation of rate expressions for some reaction types.
+
     """
     global _valsp
     global _valrxn

interfaces/cython/cantera/mixture.pyx

@@ -74,7 +74,7 @@ cdef class Mixture:
             return self.mix.nElements()
 
     cpdef int element_index(self, element) except *:
-        """Index of element with name 'element'::
+        """Index of element with name 'element'.
 
             >>> mix.element_index('H')
             2

interfaces/cython/cantera/onedim.py

@@ -187,7 +187,7 @@ def _array_property(attr, size=None):
     else:
         extradoc = "\nReturns an array of size `%s` x `n_points`." % size
 
-    doc = _trim(getattr(Solution, attr).__doc__) + extradoc
+    doc = _trim(getattr(Solution, attr).__doc__) +'\n' + extradoc
     return property(getter, doc=doc)
 
 # Add scalar properties to FlameBase

interfaces/cython/cantera/onedim.pyx

@@ -5,6 +5,7 @@ cdef class Domain1D:
     def __cinit__(self, *args, **kwargs):
         self.domain = NULL
 
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, *args, name=None, **kwargs):
         if self.domain is NULL:
             raise TypeError("Can't instantiate abstract class Domain1D.")
@@ -170,6 +171,7 @@ cdef class Boundary1D(Domain1D):
     def __cinit__(self, *args, **kwargs):
         self.boundary = NULL
 
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, *args, _SolutionBase phase, **kwargs):
         if self.boundary is NULL:
             raise TypeError("Can't instantiate abstract class Boundary1D.")
@@ -440,6 +442,7 @@ cdef class Sim1D:
     def __cinit__(self, *args, **kwargs):
         self.sim = NULL
 
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, domains, *args, **kwargs):
         cdef vector[CxxDomain1D*] D
         cdef Domain1D d
@@ -744,6 +747,7 @@ cdef class Sim1D:
              loglevel=1):
         """
         Save the solution in XML format.
+
         :param filename:
             solution file
         :param name:

interfaces/cython/cantera/reactor.pyx

@@ -11,6 +11,7 @@ cdef class ReactorBase:
     def __cinit__(self, *args, **kwargs):
         self.rbase = newReactor(stringify(self.reactor_type))
 
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, ThermoPhase contents=None, name=None, **kwargs):
         self._inlets = []
         self._outlets = []
@@ -142,6 +143,7 @@ cdef class Reactor(ReactorBase):
     def __cinit__(self, *args, **kwargs):
         self.reactor = <CxxReactor*>(self.rbase)
 
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, contents=None, *, name=None, energy='on', **kwargs):
         """
         :param contents:
@@ -364,6 +366,7 @@ cdef class Wall:
     temperature of the reactor it faces.
     """
 
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, left, right, *, name=None, A=None, K=None, U=None,
                  Q=None, velocity=None, kinetics=(None,None)):
         """
@@ -543,6 +546,7 @@ cdef class FlowDevice:
         # Children of this abstract class are responsible for allocating dev
         self.dev = NULL
 
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, upstream, downstream, *, name=None):
         assert self.dev != NULL
         self._rate_func = None
@@ -602,6 +606,7 @@ cdef class MassFlowController(FlowDevice):
     def __cinit__(self, *args, **kwargs):
         self.dev = new CxxMassFlowController()
 
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, upstream, downstream, *, name=None, mdot=None):
         super().__init__(upstream, downstream, name=name)
         if mdot is not None:
@@ -650,6 +655,7 @@ cdef class Valve(FlowDevice):
     def __cinit__(self, *args, **kwargs):
         self.dev = new CxxValve()
 
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, upstream, downstream, *, name=None, K=None):
         super().__init__(upstream, downstream, name=name)
         if K is not None:
@@ -696,6 +702,7 @@ cdef class PressureController(FlowDevice):
     def __cinit__(self, *args, **kwargs):
         self.dev = new CxxPressureController()
 
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, upstream, downstream, *, name=None, master=None, K=None):
         super().__init__(upstream, downstream, name=name)
         if master is not None:

interfaces/cython/cantera/thermo.pyx

@@ -22,6 +22,7 @@ cdef class ThermoPhase(_SolutionBase):
     Class `ThermoPhase` is not usually instantiated directly. It is used
     as a base class for classes `Solution` and `Interface`.
     """
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         if 'source' not in kwargs:
@@ -270,7 +271,7 @@ cdef class ThermoPhase(_SolutionBase):
 
     property Y:
         """
-        Get/Set the species mass fractions. Can be set as an array, as a dict,
+        Get/Set the species mass fractions. Can be set as an array, as a dictionary,
         or as a string. Always returns an array::
 
             >>> phase.Y = [0.1, 0, 0, 0.4, 0, 0, 0, 0, 0.5]
@@ -291,7 +292,7 @@ cdef class ThermoPhase(_SolutionBase):
 
     property X:
         """
-        Get/Set the species mole fractions. Can be set as an array, as a dict,
+        Get/Set the species mole fractions. Can be set as an array, as a dictionary,
         or as a string. Always returns an array::
 
             >>> phase.X = [0.1, 0, 0, 0.4, 0, 0, 0, 0, 0.5]

interfaces/cython/cantera/transport.pyx

@@ -22,6 +22,7 @@ cdef class Transport(_SolutionBase):
 
     Not all transport properties are implemented in all transport models.
     """
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, *args, **kwargs):
         if self.transport == NULL:
             self.transport = newDefaultTransportMgr(self.thermo)
@@ -109,6 +110,7 @@ cdef class DustyGasTransport(Transport):
     is handled. The viscosity, thermal conductivity, and thermal diffusion
     coefficients are not implemented.
     """
+    # The signature of this function causes warnings for Sphinx documentation
     def __init__(self, *args, **kwargs):
         self.transport = newTransportMgr(stringify("DustyGas"), self.thermo)
         super().__init__(*args, **kwargs)