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: sage-9.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:

Status badges

Description (last modified by Ralf Stephan)

The classes in symbolic/function.pyx need better docs, esp. the parameters.

Change History (24)

comment:1 Changed 5 years ago by Ralf Stephan

Description: modified (diff)

comment:2 Changed 5 years ago by Ralf Stephan

Branch: u/rws/document_function_initialization_parameters

comment:3 Changed 5 years ago by Ralf Stephan

Authors: Ralf Stephan
Commit: d8ae5e216190f013001529f28a1d03d9cf86c879
Description: modified (diff)
Status: newneeds_review

New commits:

d8ae5e224398: Document function initialization parameters

comment:4 Changed 5 years ago by Ralf Stephan

Component: symbolicsdocumentation

comment:5 Changed 5 years ago by git

Commit: d8ae5e216190f013001529f28a1d03d9cf86c8793cd27de951bfb26282570a24bc80ea401ef1cbc2

Branch pushed to git repo; I updated commit sha1. New commits:

3cd27de24398: remove include of other documents

comment:6 Changed 4 years ago by Bryan Gin-ge Chen

This documentation is really helpful!

Suggestions:

  • In src/doc/en/reference/functions/index.rst, add a link to src/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 out-of-scope 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 around sage.symbolic.function.sfunction_serial_dict

comment:7 Changed 4 years ago by Dima Pasechnik

Milestone: sage-8.2sage-8.5
Type: taskenhancement

I'm willing to give this a positive review once comment 6 is addressed.

comment:8 Changed 4 years ago by Jeroen Demeyer

Two quick comments:

  1. `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.

  1. Can you limit line lengths? Some lines are rather long.

comment:9 Changed 3 years ago by Eric Gourgoulhon

Branch: u/rws/document_function_initialization_parameterspublic/symbolic/document_functions-24398
Commit: 3cd27de951bfb26282570a24bc80ea401ef1cbc2e1db2f9bdefc78821e085d54aa53338bdfc78e85

New commits:

8320200Merge branch 'u/rws/document_function_initialization_parameters' of git://trac.sagemath.org/sage into Sage 9.0.beta7
e1db2f9Minor fixes in the documentation of symbolic functions (trac 24398)

comment:10 Changed 3 years ago by Dima Pasechnik

Milestone: sage-8.5sage-9.0

comment:11 Changed 3 years ago by Eric Gourgoulhon

Milestone: sage-9.0sage-8.5

The above commit implements the corrections suggested in comment:6 and comment:8. It would be nice to have this in Sage 9.0...

Last edited 3 years ago by Eric Gourgoulhon (previous) (diff)

comment:12 Changed 3 years ago by Eric Gourgoulhon

Milestone: sage-8.5sage-9.0

comment:13 Changed 3 years ago by Markus Wageringel

The documentation does not build.

comment:14 Changed 3 years ago by Dima Pasechnik

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 in reply to:  14 ; Changed 3 years ago by Eric Gourgoulhon

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, special-functions say, and refer to it as :ref:`list <special-functions>`.

Last edited 3 years ago by Eric Gourgoulhon (previous) (diff)

comment:16 Changed 3 years ago by git

Commit: e1db2f9bdefc78821e085d54aa53338bdfc78e85469d0e2c8fb37eddf2e64628dfd8d1120dab89a0

Branch pushed to git repo; I updated commit sha1. New commits:

469d0e2Fix hyperlinks in the documentation of symbolic functions (trac 24398)

comment:17 in reply to:  15 Changed 3 years ago by Eric Gourgoulhon

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, special-functions say, and refer to it as :ref:`list <special-functions>`.

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 Changed 3 years ago by Dima Pasechnik

This seems to work, thanks. I'd rather use tag names like

+.. _calculus-index:

than

+.. _symbolic-calculus:

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.sphinx-doc.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 Changed 3 years ago by Dima Pasechnik

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 Dima Pasechnik

Reviewers: Markus Wageringel, Dima Pasechnik
Status: needs_reviewpositive_review

OK, let's get this in.

comment:21 in reply to:  18 ; Changed 3 years ago by Markus Wageringel

Replying to dimpase:

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?

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 in reply to:  19 Changed 3 years ago by Eric Gourgoulhon

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 in reply to:  21 Changed 3 years ago by Eric Gourgoulhon

Replying to gh-mwageringel:

Replying to dimpase:

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?

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:    - `p-adic 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 Volker Braun

Branch: public/symbolic/document_functions-24398469d0e2c8fb37eddf2e64628dfd8d1120dab89a0
Resolution: fixed
Status: positive_reviewclosed
Note: See TracTickets for help on using tickets.