#8958: Extend/clarify/normalize the conventions for Python/Cython docstrings
-----------------------------+----------------------------------------------
Reporter: leif | Owner: mvngu
Type: enhancement | Status: new
Priority: major | Milestone:
Component: documentation | Keywords: docstring, documentation string,
convention, style
Author: | Upstream: N/A
Reviewer: | Merged:
Work_issues: |
-----------------------------+----------------------------------------------
The section of the ''Developer's Guide'' on conventions for
(Python/Cython) docstrings within Sage
http://www.sagemath.org/doc/developer/conventions.html#documentation-
strings currently lacks some issues; also IMHO the usage of ''inline
literals'' for Python names/types etc., ''default-role interpreted text''
(i.e. [LaTeX] math mode) and the syntax/style of e.g. parameter and return
type descriptions should be normalized (further).
* A description of the {{{:class:}}}, {{{:meth:}}}, {{{:func:}}} etc.
roles is completely missing.
* We currently have ''at least'' both
{{{ - ``param`` -- (type, default val) other description...}}}
and
{{{ - ``param`` (type, default val) -- other description...}}},
where the latter (without the default) is used by Sphinx.
* {{{True}}} and {{{False}}} etc. are usually written/typeset as
''literals'' ({{{``True``}}}), while other Python names and types (e.g.
{{{int}}}) are not. (Perhaps a bad example, since one could even use
{{{:class:`int`}}}.)
* True function/return type descriptions use both indicative and
imperative mood, sometimes even within the same module/file. (Same for
procedures, i.e. "functions" doing something but not returning anything.)
* Some people use ''math mode'' also for isolated numbers ({{{`1`}}})
and/or numbers within words (e.g. {{{`2`-descent}}} instead of
{{{2-descent}}}), but not necessarily consistently.
The ''HTML output'' of that looks very ugly, as does e.g. that of
{{{`L`-functions}}}.
(There are at least four variants of how ''simple'' constraints or
case distinctions like "n < 42" are written, namely without mark-up,
entirely literal, partially or completely typeset in math mode, and as
mixtures of plain, literal/verbatim and math mode; "... less than 42" of
course is another option.)
* IMHO the type descriptions should be specific if a function actually
expects (or returns) some particular type.
(Once we switch to Python 3, we can use type annotations, too... ;-) )
* What about documenting potentially raised exceptions?
* Some frequently used names etc. (even e.g. {{{int}}}) could be defined
as (global) macros (e.g. {{{|int|}}}) to achieve consistent look (this
also applies to reST documentation within Sage in general).
(The above list is most probably not exhaustive, nor does it express any
importance/priority; additions welcome.)
Besides extending the documentation, we should perhaps discuss some issues
and/or hold votes for the preferred/recommended style on ''sage-devel''.
:)
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/8958>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
