#17847: Cython: embed signatures in docstrings of Sage library code
-------------------------------------+-------------------------------------
Reporter: jdemeyer | Owner:
Type: enhancement | Status: needs_review
Priority: major | Milestone: sage-6.6
Component: cython | Resolution:
Keywords: | Merged in:
Authors: Jeroen Demeyer, | Reviewers: Simon King
Simon King | Work issues:
Report Upstream: Fixed upstream, | Commit:
but not in a stable release. | cced81b8c06b2eeb436c7876e5fed356e868e334
Branch: | Stopgaps:
u/SimonKing/ticket/17847 |
Dependencies: |
-------------------------------------+-------------------------------------
Changes (by SimonKing):
* status: new => needs_review
Comment:
With the new commit, the documentation builds. I hope it builds fine.
Actually I think there should be no change to how it has previously looked
like. I didn't finish all tests yet.
Comments on the commits:
As I said, it is essential for source code inspection that embedding
information of a function is available in the docstring of a cached
version of that function. That's why I did not work on top of your branch.
Here are a couple of reasons for what I did:
- The signature is sometimes not understood by sphinx, as for sphinx both
`*` and `**` have different meanings than for the embedded signature.
Hence, the signature should be stripped from the documentation. I used a
heuristics for splitting, assuming that
- the signature appears in the first line
- it starts with the undotted name of the object resp. of its class,
followed by an opening bracket.
If this pattern is found, the first line will be removed. Note that this
if there is embedding information then the signature information will be
cut off anyway by `_extract_embedded_position`.
- When the signature is inserted, a previously empty docstring becomes
non-empty, which means that an object would appear in the documentation
that previously didn't. Worse: When an object's docstring is empty, its
`__init__` docstring was used for documentation instead. There are cases
(mainly in sage.combinat) providing documentation AND references in the
`__init__` docstring. Hence, it is essential to have them, since otherwise
the doc doesn't build. So, I let `sage_getdoc_original` use `__init__`
when nothing else is found.
- It is important that `sage_getdoc_unformatted` returns the same
docstring for a class and for an instance of the class (unless the
instance explicitly has its own `__doc__` attribute). Otherwise, each of
such instance found in a module would appear in the reference manual.
I documented my changes, and so far the tests have passed. Hence: Needs
review!
--
Ticket URL: <http://trac.sagemath.org/ticket/17847#comment:76>
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 unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/d/optout.
