Opened 5 years ago
Closed 3 years ago
#24398 closed enhancement (fixed)
Document function initialization parameters
Reported by:  Ralf Stephan  Owned by:  

Priority:  major  Milestone:  sage9.0 
Component:  documentation  Keywords:  
Cc:  Merged in:  
Authors:  Ralf Stephan  Reviewers:  Markus Wageringel, Dima Pasechnik 
Report Upstream:  N/A  Work issues:  
Branch:  469d0e2 (Commits, GitHub, GitLab)  Commit:  469d0e2c8fb37eddf2e64628dfd8d1120dab89a0 
Dependencies:  Stopgaps: 
Description (last modified by )
The classes in symbolic/function.pyx
need better docs, esp. the parameters.
Change History (24)
comment:1 Changed 5 years ago by
Description:  modified (diff) 

comment:2 Changed 5 years ago by
Branch:  → u/rws/document_function_initialization_parameters 

comment:3 Changed 5 years ago by
Authors:  → Ralf Stephan 

Commit:  → d8ae5e216190f013001529f28a1d03d9cf86c879 
Description:  modified (diff) 
Status:  new → needs_review 
comment:4 Changed 5 years ago by
Component:  symbolics → documentation 

comment:5 Changed 5 years ago by
Commit:  d8ae5e216190f013001529f28a1d03d9cf86c879 → 3cd27de951bfb26282570a24bc80ea401ef1cbc2 

Branch pushed to git repo; I updated commit sha1. New commits:
3cd27de  24398: remove include of other documents

comment:6 Changed 4 years ago by
This documentation is really helpful!
Suggestions:
 In
src/doc/en/reference/functions/index.rst
, add a link tosrc/sage/symbolic/function.pyx
 Presumably you meant to remove the fragment at the end of this line
+ * :class:`BuiltinFunction`: the code of these functions is written in Python; many special functions are of this type, see :doc
This may be outofscope for this ticket but it's so trivial that I must point it out:
 There is a formatting error in the docstring for
sage.symbolic.function.get_sfunction_from_serial
, there should be double backticks aroundsage.symbolic.function.sfunction_serial_dict
comment:7 Changed 4 years ago by
Milestone:  sage8.2 → sage8.5 

Type:  task → enhancement 
I'm willing to give this a positive review once comment 6 is addressed.
comment:8 Changed 4 years ago by
Two quick comments:
 `Please find extensive developer documentation for creating new functions
in the symbolic calculus module.` is not really helpful without a hyperlink to the symbolic calculus module.
 Can you limit line lengths? Some lines are rather long.
comment:9 Changed 3 years ago by
Branch:  u/rws/document_function_initialization_parameters → public/symbolic/document_functions24398 

Commit:  3cd27de951bfb26282570a24bc80ea401ef1cbc2 → e1db2f9bdefc78821e085d54aa53338bdfc78e85 
comment:10 Changed 3 years ago by
Milestone:  sage8.5 → sage9.0 

comment:11 Changed 3 years ago by
Milestone:  sage9.0 → sage8.5 

comment:12 Changed 3 years ago by
Milestone:  sage8.5 → sage9.0 

comment:14 followup: 15 Changed 3 years ago by
basically, one cannot use :doc:
to refer to index, one needs something like
list <../../../functions/index.html>
etc. I'll push a fix soon.
comment:15 followup: 17 Changed 3 years ago by
Replying to dimpase:
basically, one cannot use
:doc:
to refer to index,
Indeed. It was working in my case probably because the referred document had been already created by a previous make doc
.
one needs something like
list <../../../functions/index.html>
etc. I'll push a fix soon.
Another solution would be to add a tag in src/doc/en/reference/functions/index.rst
, specialfunctions
say, and refer to it as :ref:`list <specialfunctions>`
.
comment:16 Changed 3 years ago by
Commit:  e1db2f9bdefc78821e085d54aa53338bdfc78e85 → 469d0e2c8fb37eddf2e64628dfd8d1120dab89a0 

Branch pushed to git repo; I updated commit sha1. New commits:
469d0e2  Fix hyperlinks in the documentation of symbolic functions (trac 24398)

comment:17 Changed 3 years ago by
Replying to egourgoulhon:
Replying to dimpase:
one needs something like
list <../../../functions/index.html>
etc. I'll push a fix soon.Another solution would be to add a tag in
src/doc/en/reference/functions/index.rst
,specialfunctions
say, and refer to it as:ref:`list <specialfunctions>`
.
I've implemented the latter solution in the last commit. Do you agree it is more robust? in particular when generating the pdf documentation (I guess something like ../../../functions/index.html
would fail then).
comment:18 followup: 21 Changed 3 years ago by
This seems to work, thanks. I'd rather use tag names like
+.. _calculusindex:
than
+.. _symboliccalculus:
to make it more clear where it points to.
We have quite a number of links like <../../../foo/index.html>
in src/sage
, perhaps all such links should be replaces the way you propose?
I also wonder whether we should rather be using https://www.sphinxdoc.org/en/master/usage/extensions/autosectionlabel.html which apparently allows using headings as labels, and so explicit tags won't be needed (I must say I don't know how to enable it in our oh so transparent sphinx configs...)
comment:19 followup: 22 Changed 3 years ago by
it appears that autosectionlabel
doesn't fly well with Sage (one gets name clashes all over the place, from autogenerated rst files). So unless this is reworked somehow we can't use it.
comment:20 Changed 3 years ago by
Reviewers:  → Markus Wageringel, Dima Pasechnik 

Status:  needs_review → positive_review 
OK, let's get this in.
comment:21 followup: 23 Changed 3 years ago by
Replying to dimpase:
We have quite a number of links like
<../../../foo/index.html>
insrc/sage
, perhaps all such links should be replaces the way you propose?
As far as I know, the tags only work within a single sphinx document, but we have many documents which is a reason for many of the relative links to exist.
comment:22 Changed 3 years ago by
Replying to dimpase:
it appears that
autosectionlabel
doesn't fly well with Sage (one gets name clashes all over the place, from autogenerated rst files). So unless this is reworked somehow we can't use it.
Thanks for having given it a try. This certainly would have been a better solution...
comment:23 Changed 3 years ago by
Replying to ghmwageringel:
Replying to dimpase:
We have quite a number of links like
<../../../foo/index.html>
insrc/sage
, perhaps all such links should be replaces the way you propose?As far as I know, the tags only work within a single sphinx document, but we have many documents which is a reason for many of the relative links to exist.
Not always: the following links are inside the same document (the reference manual):
rings/big_oh.py:  `asymptotic expansions <../../../asymptotic/index.html>`_ rings/big_oh.py:  `padic numbers <../../../padics/index.html>`_ rings/big_oh.py:  `power series <../../../power_series/index.html>`_ rings/big_oh.py:  `polynomials <../../../polynomial_rings/index.html>`_ rings/asymptotic/asymptotic_ring.py:`coercion <../../../../coercion/index.html>`_.
comment:24 Changed 3 years ago by
Branch:  public/symbolic/document_functions24398 → 469d0e2c8fb37eddf2e64628dfd8d1120dab89a0 

Resolution:  → fixed 
Status:  positive_review → closed 
New commits:
24398: Document function initialization parameters