Comments (5)
Yep second example poses no issue, since the indentation helps us determining it's still within the section (and section item).
We could add an option to the numpy parser? This way, no breaking change, and users can still opt-in to be able to have blank lines in sections (while needing double blank lines to separate prose from sections or inversely.
from griffe.
Thanks for the report!
I find it weird that
Returns
-------
only_item : type
Description.
Something.
...would be parsed as a single Returns section. How do you intertwine prose and semantic sections? Is that not possible with Numpydoc's spec? And how should Something.
be integrated within the Returns section? I think supporting blank lines in-between items is very niche. IMO it costs nothing to just remove the blank line, and it even makes the docstring more readable.
However this is just my opinion, and I'm fine with anything that matches the spec: I'm not using this docstring style after all, so those who actually use it know better 🙂 Reading again the spec at https://numpydoc.readthedocs.io/en/latest/format.html, it seems indeed that prose is not expected in-between sections, and therefore headings (and dash lines) are the true sections delimiters, not blank lines.
from griffe.
Hmm... I dug a bit deeper, and it looks like sphinx does allow including extra narrative (to a degree).
It seems like the rule they use to end a section (sphinx code here) is...
- Encounter a new section, OR
- 2 empty lines in the table block
So maybe this could be a nice compromise? I didn't realize that numpydoc and sphinx both have parsers :/
from griffe.
Parsers, parsers everywhere!
Thanks for investigating, the double blank line seems like a good compromise indeed. That's a breaking change though 🤔
from griffe.
That's a breaking change though 🤔
Yeah, it's a tough spot :/. For what it's worth, I think there are libraries using sphinx in the wild that that include empty lines in their parameter tables. I haven't seen people add narrative to sections like parameters, so am in favor of breaking changes there 😬 (but if it's helpful, we could also refactor the numpy parser to be a class, and then I could subclass it as a new parser implementation somewhere?).
Here's an example docstring from the pandas DataFrame docs:
Two-dimensional, size-mutable, potentially heterogeneous tabular data.
Data structure also contains labeled axes (rows and columns).
Arithmetic operations align on both row and column labels. Can be
thought of as a dict-like container for Series objects. The primary
pandas data structure.
Parameters
----------
data : ndarray (structured or homogeneous), Iterable, dict, or DataFrame
Dict can contain Series, arrays, constants, dataclass or list-like objects. If
data is a dict, column order follows insertion-order. If a dict contains Series
which have an index defined, it is aligned by its index. This alignment also
occurs if data is a Series or a DataFrame itself. Alignment is done on
Series/DataFrame inputs.
If data is a list of dicts, column order follows insertion-order.
index : Index or array-like
Index to use for resulting frame. Will default to RangeIndex if
no indexing information part of input data and no index provided.
columns : Index or array-like
Column labels to use for resulting frame when data does not have them,
defaulting to RangeIndex(0, 1, 2, ..., n). If data contains column labels,
will perform column selection instead.
dtype : dtype, default None
Data type to force. Only a single dtype is allowed. If None, infer.
copy : bool or None, default None
Copy data from inputs.
For dict data, the default of None behaves like ``copy=True``. For DataFrame
or 2d ndarray input, the default of None behaves like ``copy=False``.
If data is a dict containing one or more Series (possibly of different dtypes),
``copy=False`` will ensure that these inputs are not copied.
.. versionchanged:: 1.3.0
...
numpy.array (maybe less of an issue, since empty lines are in parameter descriptions):
array(object, dtype=None, *, copy=True, order='K', subok=False, ndmin=0,
like=None)
Create an array.
Parameters
----------
object : array_like
An array, any object exposing the array interface, an object whose
__array__ method returns an array, or any (nested) sequence.
If object is a scalar, a 0-dimensional array containing object is
returned.
dtype : data-type, optional
The desired data-type for the array. If not given, then the type will
be determined as the minimum type required to hold the objects in the
sequence.
copy : bool, optional
If true (default), then the object is copied. Otherwise, a copy will
only be made if __array__ returns a copy, if obj is a nested sequence,
or if a copy is needed to satisfy any of the other requirements
(`dtype`, `order`, etc.).
order : {'K', 'A', 'C', 'F'}, optional
Specify the memory layout of the array. If object is not an array, the
newly created array will be in C order (row major) unless 'F' is
specified, in which case it will be in Fortran order (column major).
If object is an array the following holds.
===== ========= ===================================================
order no copy copy=True
===== ========= ===================================================
'K' unchanged F & C order preserved, otherwise most similar order
'A' unchanged F order if input is F and not C, otherwise C order
'C' C order C order
'F' F order F order
===== ========= ===================================================
When ``copy=False`` and a copy is made for other reasons, the result is
the same as if ``copy=True``, with some exceptions for 'A', see the
Notes section. The default order is 'K'.
subok : bool, optional
If True, then sub-classes will be passed-through, otherwise
the returned array will be forced to be a base-class array (default).
ndmin : int, optional
Specifies the minimum number of dimensions that the resulting
array should have. Ones will be prepended to the shape as
needed to meet this requirement.
like : array_like, optional
Reference object to allow the creation of arrays which are not
NumPy arrays. If an array-like passed in as ``like`` supports
the ``__array_function__`` protocol, the result will be defined
by it. In this case, it ensures the creation of an array object
compatible with that passed in via this argument.
.. versionadded:: 1.20.0
from griffe.
Related Issues (20)
- Get class parameters from parent's __init__ HOT 2
- RecursionError with Griffe, Material HOT 1
- API checks: double pass, static+dynamic analysis
- Numpy docstring for fixed set of values
- Skip Alias Resolution HOT 7
- numpydoc sections not represented as its own block, if first in docstring HOT 3
- fuzzing: Failing cases found with pysource-codegen HOT 6
- API checks: Don't report type-guarded objects HOT 4
- API checks: Improve reporting for attribute who lost their value
- Module overrides member HOT 3
- feature: Expressions modernization HOT 1
- not all members have is_package/is_module HOT 3
- class attribute has label 'instance-attribute' HOT 3
- feature: Support meson-python's editable installs
- bug: property and cached_property of dataclasses are class parameters HOT 1
- bug: A dataclass field with init=False should not be a parameter HOT 3
- bug: parameter kinds for dataclasses should match the non-dataclass equivalents
- bug: MkDocs !!! and ??? admonitions can no longer be parsed HOT 3
- bug: Regular classes that inherit dataclass do not get dataclass parameters HOT 1
- bug: A class that derives from a dataclass should be labelled a dataclass HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from griffe.