From: Guenter M. <mi...@us...> - 2017-10-07 16:19:01
|
On 2017-10-04, Antony Lee wrote: > Hi all, > Currently, RST specifies that entries in a definition list may be followed > by a series of classifiers all on the same line, as in > term : classifier one : classifier 2 > Definition > This syntax is used by numpydoc (the de facto docstring standard in the > scientific Python world) to document individual parameters of > callables, as in > parameter_name : type_of_parameter > Description of the parameter. > (see > https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#sections > for details). > In general, this approach yields highly legible raw docstrings, and can > easily be converted into the Sphinx standard field list format (tools to do > so include numpydoc and sphinx.ext.napoleon). > However, it is awkward to include very long parameter "types" (e.g., an > enumeration of allowable string values -- which I know is not strictly a > type, but remains a common API) using this method, due to the restriction > that the classifiers need to stay in one line. In practice, this means > that it is necessary to use a line continuation in the docstring, either > parameter_name : some long type \ > description > Description of parameter. > or > parameter_name : some long type \ > description > Description of the parameter. > The first form is ugly in the source, the second form is ugly when the > docstring is viewed as a string (e.g. by pydoc) as all the spaces before > ``description`` end up in the literal docstring. See e.g. > https://github.com/numpy/numpydoc/issues/87 for a longer discussion of the > issue. > While numpydoc can of course invent its own syntax, it would seem > preferable if a standard way to write multi-line classifiers was specified > by the RST standard. Are the docstrings also used with Docutils or only with Sphinx? Maybe it suffices to have the standard way not specified but compatible with the rST standard. > Just checking for indentation is actually a bit > ambiguous, because it is not clear how to parse > a : b > c > (is ``c`` a continuation or a description?). A possibility would be to > support backslashed-line continuations at the RST level, so the Python > docstring would look like > parameter_name : some long type \\ > description > Description of the parameter > but RST would see a single backslash and know what to do; or require that > continued classifier lines start also with ``: ``: > parameter_name : some long type > : description > Description of the parameter > Neither option is strictly fully back-compatible, but I hope one of them, > or some similar solution, can be adopted. Another option is a "type" role as alternative markup for long types:: .. role:: type parameter_name :type:`some long type description` Description of the parameter. Numpydoc and sphinx.ext.napoleon could then implement a transform that converts the result to be identical to the simple syntax for short "types". Günter |