Callable symbolic expressions absent from the reference manual

[Eric Gourgoulhon]

Hi,

It seems that callable symbolic expressions, as implemented in
src/sage/symbolic/callable.py,
are not included in the reference manual: there is no mention of sage/symbolic/callable in
src/doc/en/reference/calculus/index.rst
and they do not appear when asked for in the search box of the reference manual.

Is there any reason for this ?
If this is a mistake, I may open a ticket to correct it.

Eric.

[Volker Braun]

please do open a ticket!

[Eric Gourgoulhon]

Le samedi 28 février 2015 15:57:21 UTC+1, Volker Braun a écrit :

please do open a ticket!

OK. This is  #17876 (note that I've not pushed the correction yet).

Eric.

[Marc Mezzarobba]

Eric Gourgoulhon wrote:
> It seems that callable symbolic expressions, as implemented in
> src/sage/symbolic/callable.py,
> are not included in the reference manual: there is no mention of
> sage/symbolic/callable in
> src/doc/en/reference/calculus/index.rst
> and they do not appear when asked for in the search box of the
> reference manual.

There are *tons* of modules missing from the reference manual, some
obsolete, some still in pre-sphinx style or with rst syntax errors, some
whose user documentation in fact appears in another module, and many
apparently just forgotten.

A few weeks ago I started systematically adding those that didn't look
like they were intentionally omitted, with minimal fixes to the broken
docstrings so that the manual still builds (but not necessarily that the
new chapters look good).

If someone wants to help, see u/mmezzarobba/wip/refman on trac (already
bitrotten I'm sure, but probably still useful).

In terms of included modules I'm somewhere in sage/modular (in
alphabetical order), with lots of sphinx errors remaining in the newly
included ones. In most cases I added the missing modules to the
corresponding tables of contents in more or less random order, the idea
being to do a second pass to rationalize the structure once we have a
clearer idea of the full list of modules.

--
Marc

[Eric Gourgoulhon]

Hi Marc,

Le samedi 28 février 2015 17:07:33 UTC+1, Marc Mezzarobba a écrit :

There are *tons* of modules missing from the reference manual, some
obsolete, some still in pre-sphinx style or with rst syntax errors, some
whose user documentation in fact appears in another module, and many
apparently just forgotten.

OK I see...
 

A few weeks ago I started systematically adding those that didn't look
like they were intentionally omitted, with minimal fixes to the broken
docstrings so that the manual still builds (but not necessarily that the
new chapters look good).

Very good! Then clearly the ticket #17876 is irrelevant. How can we suppress it ? (Maybe mark it as duplicate once your ticket is opened ?)

If someone wants to help, see u/mmezzarobba/wip/refman on trac (already
bitrotten I'm sure, but probably still useful).

In terms of included modules I'm somewhere in sage/modular (in
alphabetical order), with lots of sphinx errors remaining in the newly
included ones. In most cases I added the missing modules to the
corresponding tables of contents in more or less random order, the idea
being to do a second pass to rationalize the structure once we have a
clearer idea of the full list of modules.

Good luck! (this seems an impressive amount of work).

Best regards,

Eric.

[Marc Mezzarobba]

Eric Gourgoulhon wrote:
> Then clearly the ticket #17876 is irrelevant.

Not necessarily: I have no idea when (or if) I will be able to finish
going through all missing modules, or even when I will have time to
bring the existing part to a state where it can be reviewed without
waiting for the rest...

--
Marc

[Vincent Delecroix]

Hi Marc,

I already added sage/misc/sage_input.py in #17748 and Nathan added
combinat/permutations_cython.pyx in #17848. So it is highly probable
that your branch conflicts with the current and/or next beta.

Vincent

> --
> You received this message because you are subscribed to the Google Groups
> "sage-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sage-devel+...@googlegroups.com.
> To post to this group, send email to sage-...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.
>

[Marc Mezzarobba]

Vincent Delecroix wrote:
> I already added sage/misc/sage_input.py in #17748 and Nathan added
> combinat/permutations_cython.pyx in #17848. So it is highly probable
> that your branch conflicts with the current and/or next beta

Yes, I noticed. No problem, your sphinx-ifications are probably much
more careful than mine, and I intend to rebase and clean up my branch in
any case. But thanks for the notice!

--
Marc

[Simon King]

Hi!

I guess a single ticket whose purpose is to add and fix all
documentation to the manual would be a nightmare to maintain. Wouldn't
it be easier to have one ticket for each module that is missing in the
documentation?

Best regards,
Simon

[Vincent Delecroix]

On 28/02/2015, Simon King <simon...@uni-jena.de> wrote:
> I guess a single ticket whose purpose is to add and fix all
> documentation to the manual would be a nightmare to maintain. Wouldn't
> it be easier to have one ticket for each module that is missing in the
> documentation?

+1
And easier to review!

But it would be cool to also have a meta-ticket that gathers the information.

Vincent

[Marc Mezzarobba]

Simon King wrote:
> I guess a single ticket whose purpose is to add and fix all
> documentation to the manual would be a nightmare to maintain. Wouldn't
> it be easier to have one ticket for each module that is missing in the
> documentation?

Yes, it would! And I'm not planning to submit it all in a single ticket.
But what I have done at this point is (very) messy and needs more work
before it can easily be split in independent units.

--
Marc

[Eric Gourgoulhon]

OK.  I've just added a branch to the ticket then.

Best regards,

Eric.

--
Marc

[Nicolas M. Thiery]

On Sat, Feb 28, 2015 at 05:07:18PM +0100, Marc Mezzarobba wrote:
> There are *tons* of modules missing from the reference manual, some
> obsolete, some still in pre-sphinx style or with rst syntax errors, some
> whose user documentation in fact appears in another module, and many
> apparently just forgotten.
>
> A few weeks ago I started systematically adding those that didn't look
> like they were intentionally omitted, with minimal fixes to the broken
> docstrings so that the manual still builds (but not necessarily that the
> new chapters look good).

Great, thanks!

For the record: In #16256, we made sure that all current modules in
sage.combinat were included in the reference manual, and did a first
step in the direction of automatizing the building of the module list,
so that not including one would never happen again. At this point it
still is necessary to running manually a shell command; there remains
to have sphinx build the list of modules automatically::

http://www.sagemath.org/doc/reference/combinat/module_list.html

Cheers,
Nicolas
--
Nicolas M. Thiéry "Isil" <nth...@users.sf.net>
http://Nicolas.Thiery.name/

[Marc Mezzarobba]

Marc Mezzarobba wrote:
> There are *tons* of modules missing from the reference manual, some
> obsolete, some still in pre-sphinx style or with rst syntax errors,
> some whose user documentation in fact appears in another module, and
> many apparently just forgotten.
>
> A few weeks ago I started systematically adding those that didn't look
> like they were intentionally omitted, with minimal fixes to the broken
> docstrings so that the manual still builds (but not necessarily that
> the new chapters look good).

[...]

> In most cases I added the missing modules to the
> corresponding tables of contents in more or less random order, the
> idea being to do a second pass to rationalize the structure once we
> have a clearer idea of the full list of modules.

The first few patches are up for review:

http://trac.sagemath.org/ticket/17929
http://trac.sagemath.org/ticket/17930
http://trac.sagemath.org/ticket/17931
http://trac.sagemath.org/ticket/17932
http://trac.sagemath.org/ticket/17933

Also related is the following attempt to clarify the main table of
contents:

http://trac.sagemath.org/ticket/17934

--
Marc

[Marc Mezzarobba]

Marc Mezzarobba wrote:
> There are *tons* of modules missing from the reference manual, some
> obsolete, some still in pre-sphinx style or with rst syntax errors,
> some whose user documentation in fact appears in another module, and
> many apparently just forgotten.
>
> A few weeks ago I started systematically adding those that didn't look
> like they were intentionally omitted, with minimal fixes to the broken
> docstrings so that the manual still builds (but not necessarily that
> the new chapters look good).

[...]

> In most cases I added the missing modules to the
> corresponding tables of contents in more or less random order, the
> idea being to do a second pass to rationalize the structure once we
> have a clearer idea of the full list of modules.

Second part:

http://trac.sagemath.org/ticket/18161 # repl, needs review
http://trac.sagemath.org/ticket/18162 # plot, needs review
http://trac.sagemath.org/ticket/18163 # modules, needs review
http://trac.sagemath.org/ticket/18164 # coding, thanks Frédéric for the review!
http://trac.sagemath.org/ticket/18165 # geometry, thanks Frédéric & Travis for the review!
http://trac.sagemath.org/ticket/18166 # calculus, needs review
http://trac.sagemath.org/ticket/18167 # schemes, needs review
http://trac.sagemath.org/ticket/18168 # quadratic_forms, needs review
http://trac.sagemath.org/ticket/18169 # rings, needs review
http://trac.sagemath.org/ticket/18170 # others, needs review

Also

http://trac.sagemath.org/ticket/17932

from the first part still needs review.

--
Marc