From f0bb0f8492c84660b43290a8e65e9780f9cf9078 Mon Sep 17 00:00:00 2001 From: "Bryan W. Weber" Date: Tue, 26 Aug 2014 22:04:59 +0000 Subject: [PATCH] [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 | 2 +- doc/sphinx/cti/phases.rst | 6 +++--- interfaces/cython/cantera/ctml_writer.py | 6 ++++-- interfaces/cython/cantera/mixture.pyx | 2 +- interfaces/cython/cantera/onedim.py | 2 +- interfaces/cython/cantera/onedim.pyx | 4 ++++ interfaces/cython/cantera/reactor.pyx | 7 +++++++ interfaces/cython/cantera/thermo.pyx | 5 +++-- interfaces/cython/cantera/transport.pyx | 2 ++ 9 files changed, 26 insertions(+), 10 deletions(-) diff --git a/doc/sphinx/cti/input-files.rst b/doc/sphinx/cti/input-files.rst index e68437ff9..5a24c3f7c 100644 --- a/doc/sphinx/cti/input-files.rst +++ b/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 diff --git a/doc/sphinx/cti/phases.rst b/doc/sphinx/cti/phases.rst index d3b11de05..e57aa3407 100644 --- a/doc/sphinx/cti/phases.rst +++ b/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:: diff --git a/interfaces/cython/cantera/ctml_writer.py b/interfaces/cython/cantera/ctml_writer.py index 716c1786a..130bdd41e 100644 --- a/interfaces/cython/cantera/ctml_writer.py +++ b/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 diff --git a/interfaces/cython/cantera/mixture.pyx b/interfaces/cython/cantera/mixture.pyx index 0dd7c5396..86392e5ba 100644 --- a/interfaces/cython/cantera/mixture.pyx +++ b/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 diff --git a/interfaces/cython/cantera/onedim.py b/interfaces/cython/cantera/onedim.py index 4dc13ea2b..6ee30fbe0 100644 --- a/interfaces/cython/cantera/onedim.py +++ b/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 diff --git a/interfaces/cython/cantera/onedim.pyx b/interfaces/cython/cantera/onedim.pyx index f35ed2f52..0ad2b2c57 100644 --- a/interfaces/cython/cantera/onedim.pyx +++ b/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: diff --git a/interfaces/cython/cantera/reactor.pyx b/interfaces/cython/cantera/reactor.pyx index 437674f15..15080efa2 100644 --- a/interfaces/cython/cantera/reactor.pyx +++ b/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 = (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: diff --git a/interfaces/cython/cantera/thermo.pyx b/interfaces/cython/cantera/thermo.pyx index 39a9df640..11a043214 100644 --- a/interfaces/cython/cantera/thermo.pyx +++ b/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] diff --git a/interfaces/cython/cantera/transport.pyx b/interfaces/cython/cantera/transport.pyx index aa509cefa..d37eac166 100644 --- a/interfaces/cython/cantera/transport.pyx +++ b/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)