Ref: add various missing modules to the reference manual

[mezzarobba]

Component: documentation

Author: Marc Mezzarobba

Branch: 8e47f6a

Reviewer: Jeroen Demeyer

Issue created by migration from https://trac.sagemath.org/ticket/18170

[mezzarobba]

Branch: u/mmezzarobba/ref-other

[mezzarobba]

Author: Marc Mezzarobba

[mezzarobba]

Commit: 2ceb598

[mezzarobba]

New commits:

30599c4	games.hexad: rst fixes
a3261b8	sandpiles.sandpiles: rst fixes
ca7ac34	matroids_plot_helpers: rst fixes
087cabc	modform.theta: rst fixes
f736624	cunningham_tables: rst fixes
1df5afb	monoids.strings_ops: rst fixes
6858c7f	stats.r: rst fixes
558761d	Ref: remove duplicate entry in r/algebras
2ceb598	Ref: add missing modules to various parts of the manual

[kcrisman]

comment:3

Are things like

+.. backends depending on optional packages
+..   sage/numerical/backends/coin_backend
+..   sage/numerical/backends/cplex_backend
+..   sage/numerical/backends/gurobi_backend
+

some Sphinx directive I'm not familiar with? Or are the .. bits there superfluous?

[mezzarobba]

comment:4

Replying to @kcrisman:

Are things like

+.. backends depending on optional packages
+..   sage/numerical/backends/coin_backend
+..   sage/numerical/backends/cplex_backend
+..   sage/numerical/backends/gurobi_backend
+

some Sphinx directive I'm not familiar with? Or are the .. bits there superfluous?

Just comments. For some reason making a single comment block confuses the docbuilder, while it works if I comment each line with .. (which is valid rst syntax as far as I know).

[kcrisman]

comment:5

In that case, why not just include those (and the

+.. optional - cryptominisat

ones) and just make it really clear that they depend on optional packages? We certainly get plenty of questions about MILP and backends, for instance.

[mezzarobba]

comment:6

Unfortunately, the doc building system fails (and complains loudly) if it can't import a module listed in one of the toctree blocks.

[kcrisman]

comment:7

Oh yeah, I forgot about that. Hmm, that is annoying. Perhaps (not necessarily here) one could write a document referring to these which explain anything useful in them, but which is a pure documentation module. (I know there is a thematic tutorial about these already in existence that explains a lot of it.)

[fchapoton]

Changed branch from u/mmezzarobba/ref-other to public/ticket/18170

[fchapoton]

comment:8

just made sure that doc builds

---

New commits:

61a61cd	Merge branch 'u/mmezzarobba/ref-other' into 6.7.b1
c4f829a	trac #18170 just making sure doc builds

[fchapoton]

Changed commit from 2ceb598 to c4f829a

[jdemeyer]

comment:9

What's this additional "docstring" in src/sage/sandpiles/sandpile.py?

"""
To calculate linear systems associated with divisors, 4ti2 must be installed.
One way to do this is to run sage -i to install glpk, then 4ti2. See
http://sagemath.org/download-packages.html to get the exact names of these
packages. An alternative is to install 4ti2 separately, then point the
following variable to the correct path.
"""

Shouldn't this be moved to the main docstring?

[jdemeyer]

comment:10

This TOC entry is duplicated:

sage/rings/finite_rings/hom_finite_field

[jdemeyer]

comment:11

Abstract SAT Solver. -> Abstract SAT Solver

[jdemeyer]

comment:12

I would prefer to see

sage/modular/modform/notes

in a separate sub-section of the TOC.

[jdemeyer]

comment:13

PDF docs do not build:

! Undefined control sequence.
l.4316 the model of the curves $X_0(p) = \PP
                                            ^1$ are specified by quotients of
? 
! Emergency stop.
l.4316 the model of the curves $X_0(p) = \PP
                                            ^1$ are specified by quotients of
!  ==> Fatal error occurred, no output PDF file produced!

[mezzarobba]

comment:14

Replying to @fchapoton:

just made sure that doc builds

---

New commits:

61a61cd	Merge branch 'u/mmezzarobba/ref-other' into 6.7.b1
c4f829a	trac #18170 just making sure doc builds

Thanks! But actually the fixes to number_field/* were on the branch about reference/rings (#18169). So the problem here is that I apparently put some of the changes to index files depending on these fixes on this ticket's branch instead of the other one, and then made a mistake while testing that the tickets were independent. Anyway, I'm now rebasing both branches—and dropping your commit in the process to avoid conflicts.

[mezzarobba]

New commits:

92b276a	games.hexad: rst fixes
80590b7	sandpiles.sandpiles: rst fixes
d862438	matroids_plot_helpers: rst fixes
776d9bd	modform.theta: rst fixes
ba3aa08	cunningham_tables: rst fixes
7dbf569	monoids.strings_ops: rst fixes
4e7150b	stats.r: rst fixes
905af71	Ref: remove duplicate entry in r/algebras
066a114	Ref: add missing modules to various parts of the manual
8e47f6a	#18170 make pdf docs build + cosmetic fixes

[mezzarobba]

Changed commit from c4f829a to 8e47f6a

[mezzarobba]

Changed branch from public/ticket/18170 to u/mmezzarobba/ref-other

[jdemeyer]

comment:16

positive_review if it builds properly.

[vbraun]

comment:17

Reviewer name missing

[jdemeyer]

Reviewer: Jeroen Demeyer

[vbraun]

Changed branch from u/mmezzarobba/ref-other to 8e47f6a

[jhpalmieri]

Changed commit from 8e47f6a to none

[jhpalmieri]

comment:20

I'm confused about what the lines

   sage/groups/perm_gps/partn_ref
   sage/groups/perm_gps/partn_ref2

in reference/groups/index.rst were supposed to accomplish, because in Sage 8.1.beta4, they lead to useless pages. (See http://doc.sagemath.org/html/en/reference/groups/sage/groups/perm_gps/partn_ref.html, for example.) Can anyone clarify?

(I would open a follow up ticket, but I think a good ticket description ought to say what is intended, and I have no idea in this case.)

[jdemeyer]

comment:21

I guess what was meant is the various modules inside those directories instead of the empty __init__.py module: #23839

[mezzarobba]

comment:22

Replying to @jhpalmieri:

I'm confused about what the lines

   sage/groups/perm_gps/partn_ref
   sage/groups/perm_gps/partn_ref2

in reference/groups/index.rst were supposed to accomplish, because in Sage 8.1.beta4, they lead to useless pages. (See http://doc.sagemath.org/html/en/reference/groups/sage/groups/perm_gps/partn_ref.html, for example.) Can anyone clarify?

I don't remember for sure, sorry, but I guess Jeroen is right. (Most probably, I automated part of the changes and didn't notice the issue.) In any case, the general goal of the branch was to ensure that all sage modules (well, except for a few special cases) were included in the reference manual.