Reorganize the documentation indexes into src/sage/combinat
Closed this issue · 177 comments
Goal: reorganize the documentation indexes into src/sage/combinat
-
For example, the thematic index
src/doc/en/reference/combinat/crystals.rstis now in:
src/sage/combinat/crystals/__init__.pyand is accessible through
sage.combinat.crystals?(potential variant: put it in all.py)
-
What's left in
doc/en/reference/combinatcan potentially be generated automatically.
This is not yet automatized; the content of module_list.rst still needs to be updated by hand; see the instructions on top of the file. -
All p/cython files in
src/sage/combinat/are now included in the reference manual -
Improved thematic indexes
-
New thematic indexes: algebraic_combinatorics, catalog_partitions,
counting, enumerated_sets -
Fixed some documentation syntax glitches here and there
-
Added the catalogs of permutation groups and matrix groups to the
reference manual so that we can link to them. Fixed the doc title of
the former. -
Added a back link from the doc of sage.dynamics
-
Added (draft of) sage.combinat.quickref
This is a follow up to #16058.
End result browsable at http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/index.html
Warning: see the note below about the current doc compilation glitch.
Discussion
One might argue that this reorganization of the documentation is not
consistent with what's done elsewhere in the manual. Indeed. I believe
sage.combinat is a good spot to explore better ways to organize the
documentation. Here are the advantages of this new organization:
-
It's more local:
E.g. everything the developer has to look at or modify about
designs, including the index, is in src/sage/combinat/design. This
is simpler for newcomers and means, e. g., less chances to forget to
update the index w.r.t. the code. -
It's more consistent with the hierarchical structure of modules. In
particular, it's agnostic of how the reference manual is split into
documents. This was not the case before: to split
sage/combinat/crystalsin its own document required to move the
thematic index about crystals fromreference/combinat/to
reference/combinat/crystals. This will ease the job of #14582. -
It's more friendly to documentation lookup using introspection
-
It's more automatic; there are less chances to forget adding a file
in the documentation which hit us often in the past. -
It enforces including all files in the documentation.
-
Writing the thematic indexes as plain lists (rather than toctrees)
is more flexible:-
one can e.g. choose to point to the main class in a file rather
than the full file. -
one can focus on the user feature and not reference technical
modules (they appear in the full module list anyway) -
one can point to related things elsewhere in the source code
-
TODO
-
Proof reading
-
Checking that the links are functional
-
Handle the various TODO's left in the indexes (typically about
choosing the right entry points for each module)Postponed to a later ticket, since those are further enhancements
not directly related to this ticket. It's just that, while browsing
through the indexes suggested them to me. -
Finish automatizing the building of module_list.rst.
Postponed to #17421
-
Sphinx issue: deciding on how to link to classes/functions
in the index we would want to have the title of the documentation of
the class rather than the name of the class; or maybe both.For now, we stick to the class name for now until we find a good way
to do this with Sphinx. -
Sphinx issue: how to crossrefs documents in the thematic tutorial.
For now we use a workaround.
-
Sphinx issue: homogeneous styles for the index links
The style used by Sphinx depends on the type of the link; this makes
the indexes look non homogeneous. See what we can do here. This is
purely about style rather than content, hence postponed to a later
ticket. -
Sphinx issue: latex support in
:ref:When the title of a module contains some latex, it gets displayed
properly in tocrefs, but not in:ref's. We had a look with
Florent, and fixing this would require some fiddling with Sphinx's
internals (the latex chunks are already stripped away in the
crossref database!). Hence postponed for later as fixing this won't
require changing the documentation sources.
Depends on #16058
Depends on #17189
CC: @sagetrac-sage-combinat @nathanncohen @tscrim @anneschilling @videlec
Component: documentation
Keywords: thematic index, quickref
Author: Nicolas M. Thiéry, Jean-Pierre Flori
Branch: 823c116
Reviewer: Anne Schilling, Nathann Cohen
Issue created by migration from https://trac.sagemath.org/ticket/16256
Description changed:
---
+++
@@ -1,16 +1,16 @@
Reorganize the documentation indexes into src/sage/combinat:
- For example, the thematic index
- src/doc/en/reference/combinat/crystals.rst is now in:
- src/sage/combinat/crystals/__init__.py and is accessible through
- sage.combinat.crystals?
+ `src/doc/en/reference/combinat/crystals.rst` is now in:
+ `src/sage/combinat/crystals/__init__.py` and is accessible through
+ `sage.combinat.crystals`?
(potential variant: put it in all.py)
-- What's left in doc/en/reference/combinat can potentially be generated automatically.
+- What's left in `doc/en/reference/combinat` can potentially be generated automatically.
This is not yet automatized; the content of module_list.rst still needs to be updated by hand; see the instructions on top of the file.
-- All p/cython files in sage/combinat/ are now included in the reference manual
+- All p/cython files in `src/sage/combinat/` are now included in the reference manual
- Improved thematic indexes
Commit: 391f7ff
New commits:
8b8aea8 | trac #16058: Organize the index of combinatorial modules |
e0d2b66 | trac #16058: Two new categories |
0293c49 | trac #16058: Another group |
82af706 | Merge branch 't/16100/keep_going_in_doc_errors' into t/16058/public/16058 |
28062ed | Experiment with moving the indexes around and toward the source tree |
63b43d4 | Merge 6.2.beta8 into t/16058/public/16058 |
499aae1 | Trac 16058: change the label in the sphinx-autodoc files for .__init__.py to |
6755031 | Trac 16058: Reorganize the documentation indexes into src/sage/combinat |
3b84036 | Trac 16058: Reorganize the documentation indexes into src/sage/combinat (follow up little fixes) |
391f7ff | Merge branch 'develop' into t/16058/public/16058 |
(btw : you can check that the links are functional with the -k --warn-links options : sage -docbuild reference/combinat -k --warn-links html)
Changed branch from u/nthiery/16058-combinat-doc-index to none
Replying to @nathanncohen:
- I have no idea how I can obtain the result from your web page with the branch you give.
Nothing special: checkout the branch and run make doc as usual.
By the way, it does not apply on the latest rc0.
I merged the trivial conflict.
- Look at that : http://sage.math.washington.edu/home/nthiery/16058-doc/combinat/sage/combinat/counting.html#sage-combinat-counting
Or that : http://sage.math.washington.edu/home/nthiery/16058-doc/combinat/sage/combinat/species/__init__.html#sage-combinat-speciesAll links are broken!
Thanks for spotting this. I had fumbled my query replace. It should be
fixed now. Well, I am recompiling Sage right now. I'll push / update
the web page shortly.
That's a problem for a reference manual ...
No, really? Never thought about that :-)
- Where are the combinatorial designs ?
Ah, yes, it somehow slipped out of the main index. Fixed. Thanks.
- Those TODO will have to be removed before it is merged anywhere.
Nicolas, it looks like your branch is not ready.
Of course.
Could you review this ticket and create another one for yours?
Will do / done.
You would also need to ask the release manager what he thinks of the script you have to run before generating the doc.
There is no such script to be run.
At this point, when there is a new module to be added, you can edit by
hand module_list.rst (as we used to do in index.rst). Or just be lazy,
and use the shell commands listed there. The point is that this step
can be automatized and is meant to be so.
Perhaps there is a pure-sphinx workaround ? I guess you asked Florent about this too ?
Yes, the plan is certainly to have module_list.rst be built
automatically by sphinx. Something similar to the building of the
other sphinx autogenerated files (in
reference/combinat/sage/combinat/*).
Right now I have no idea how it works. If you create another ticket, please explain that.
The only trick is in src/doc/en/reference/combinat/index.rst which
uses automodule to slurp in the documentation of sage.combinat which
itself is defined in sage/combinat/__init__.py
Other than that, this is just using standard ReST documentation.
WARNING: there will be some non trivial conflicts with the latest changes in #16058.
The easiest for me to resolve them is to replay my changes on top of #16058 and create a new clean branch which I am going to work on now. The branch u/nthiery/16058-combinat-doc-index is just here for display; don't work on top of it!
?....
You can merge this branch with the head of the branch #16058, too... That only produces one additional commit and no history is rewritten.
Ah, yes, it somehow slipped out of the main index. Fixed. Thanks.
Can you be sure it is the only one ?
You would also need to ask the release manager what he thinks of the script you have to run before generating the doc.
There is no such script to be run.
What is the meaning of this ?
+.. NOTE::
+
+ This is built automatically by running in src/sage/combinat::
+
+ for x in **/*.py*; do echo " sage/combinat/"`echo $x | sed 's/\.py.?$//'`; done >! /tmp/module_list
At this point, when there is a new module to be added, you can edit by
hand module_list.rst (as we used to do in index.rst). Or just be lazy,
and use the shell commands listed there. The point is that this step
can be automatized and is meant to be so.
Okay, whatever. If the addition above is not about a script that has to be run before generating the doc, it has nothing to do there.
Yes, the plan is certainly to have
module_list.rstbe built
automatically by sphinx. Something similar to the building of the
other sphinx autogenerated files (in
reference/combinat/sage/combinat/*).
What is the point of having an index like that instead of the human-made index page, i.e. the one that is being worked on on this ticket ?
Nathann
Replying to @nthiery:
I'll push / update the web page shortly.
Done. I pushed the branch too. Now working on making a clean branch.
Replying to @nathanncohen:
Can you be sure it's the only one?
I don't have a formal proof, no :-) We will have to double check this
systematically. Like for any other reorganization.
Okay, whatever. If the addition above is not about a script that has to be run before generating the doc, it has nothing to do there.
This is documentation on how to update the module_list file; the top
of this file is a natural spot for it. In any cases this is meant to
be replaced by "automatically generated file; don't touch", so there
is no point discussing it.
What is the point of having an index like that instead of the human-made index page, i.e. the one that is being worked on on this ticket ?
For the reader that's indeed essentially pointless: sphinx already
provides an index of all documented modules. However sphinx currently
needs to have somewhere a list of all the modules for which it's
supposed to build the documentation, in the form of a toctree. Other
than that, I'd be more than happy to simply get rid of it.
Pfiou, when sphinx goes into bad mode, this can be a pain to fix ... Oh well.
#16256 is now "on top" of #16058. I ended up doing it via a merge (at the end, it was no simpler than the replay I was planning to do which would have produced a cleaner history). Anyway, it's done, and the merge was the occasion to double check that everything that was in the previous index.rst is still referenced somewhere.
At this point this branch is not really ready for review, but wide open for comments.
The produced documentation has been updated.
Switching now to the review of #16058.
Last 10 new commits:
63b43d4 | Merge 6.2.beta8 into t/16058/public/16058 |
499aae1 | Trac 16058: change the label in the sphinx-autodoc files for .__init__.py to |
6755031 | Trac 16058: Reorganize the documentation indexes into src/sage/combinat |
3b84036 | Trac 16058: Reorganize the documentation indexes into src/sage/combinat (follow up little fixes) |
391f7ff | Merge branch 'develop' into t/16058/public/16058 |
ff7add9 | Fixed cross references, add title to all.py files |
a14057b | Some more groupings and separated root system types into separate list. |
4b5cb2b | trac #16058: Rebase on 6.2.rc0 |
4644c74 | Trac 16256: Merge branch 'public/16058' into u/nthiery/16058-combinat-doc-index |
d328407 | Trac 16256: fixed some cross references and doc compilation issues |
Work Issues: gather comments by showing it around, and work on the listed TODO's
Description changed:
---
+++
@@ -43,7 +43,7 @@
documents. This was not the case before: to split
`sage/combinat/crystals` in its own document required to move the
thematic index about crystals from `reference/combinat/` to
- `reference/combinat/crystals`.
+ `reference/combinat/crystals`. This will ease the job of #14582.
- It's more friendly to documentation lookup using introspection
@@ -79,3 +79,4 @@
module_list.rst.
This is a follow up to #16058.
+Hey all,
What needs to be done here?
Building the combinat doc is one of the bottleneck on my machines, so this ticket is highly wanted.
What needs to be done here?
Building the combinat doc is one of the bottleneck on my machines, so this ticket is highly wanted.
If I understand correctly what this ticket is about, it rather goes against your goal, as it means to add more files to the documentation. But is it mostly about improving the doc to make it easier to read/browse through.
On the bright side, this ticket intends to do so many things requiring the input of so many persons that you can safely assume it will ... take time before anything is done :-P
On the other hand, beware if people start creating small tickets to address independently the points mentionned above, for that's how actual work begins :-P
Nathann
I thought this ticket also split the combinat doc into a bunch of subfolders, letting it be built in parallel.
Am I wrong?
Yo !
I thought this ticket also split the combinat doc into a bunch of subfolders, letting it be built in parallel.
Am I wrong?
Well, I understood that some new index.rst files would be created, but I have no idea if this means that they will correspond to different entry points for sphinx and thus that they will be built separately O_o
This being said, if there is a way to achieve that you should probably look into Nicolas's branch to see if it is implemented already, and in any case create a second ticket to address it. Otherwise it will be held forever by the other things enumerated above.
Nathann
Branch pushed to git repo; I updated commit sha1. New commits:
b3b708b | Merge branch 't/16256/reorganize_the_documentation_indexes_into_src_sage_combinat' into combinat/reorganize_the_documentation_indexes_into_src_sage_combinat-16256 |
Hi Jean-Pierre,
Catching up with sage-trac e-mails ... sorry I had missed this one.
Replying to @jpflori:
What needs to be done here?
Building the combinat doc is one of the bottleneck on my machines, so this ticket is highly wanted.
This ticket just reorganizes the documentation so that things get
grouped nicely by sage module. But it should make it trivial to split
the documentation on top of it in #14582.
Where you could help:
-
Giving your point of view on the approach taken here.
-
If you have already played with splitting sphinx documents, giving
me a hand for #14582 -
And of course proofreading if you feel like it :-)
Cheers,
Nicolas
Description changed:
---
+++
@@ -65,6 +65,8 @@
TODO:
+- confirm that this is the right approach
+
- proof reading
- choosing the right entry points for each moduleBranch pushed to git repo; I updated commit sha1. New commits:
9d388db | Merge branch 'develop=6.4 beta2' into combinat/reorganize_the_documentation_indexes_into_src_sage_combinat-16256 |
Yo !
The link toward the result is not availble anymore, and I don't like what you are doing with combinat/designs.rst (i.e. removing the file). How will this page be replaced ?
Nathann
Oh. By the equivalent __init__.py. Nevermind :-P
Nathann
Replying to @nathanncohen:
If I understand correctly what this ticket is about, it rather goes
against your goal, as it means to add more files to the
documentation ...
Indeed, as a side effect, it adds a few files that were missing from
the reference manual; but this should not make a real difference.
On the bright side, this ticket intends to do so many things
requiring the input of so many persons that you can safely assume it
will ... take time before anything is done:-P
Be my guest and show the example by doing your share :-)
The produced documentation for the sections about graphs and designs
with this branched applied can be found respectively in:
- http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/index.html
- http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/sage/combinat/designs/__init__.html
The sources are in the corresponding __init__.py files:
- http://sage.math.washington.edu/home/nthiery/sage/src/sage/combinat/__init__.py
- http://sage.math.washington.edu/home/nthiery/sage/src/sage/combinat/designs/__init__.py
(or just clone this branch as usual)
What's to be done about those sections:
- Checking that it looks good from the user point of view
- Choosing better entry points when appropriate
(e.g. sometime it's more natural to point directly to a class than
to the module defining it). - Checking that it looks natural from the dev point of view
- Checking that nothing got lost in the operation
- Proofreading for typos
Thanks in advance,
Nicolas
Description changed:
---
+++
@@ -24,7 +24,7 @@
- Added (draft of) sage.combinat.quickref
-End result browsable at http://sage.math.washington.edu/home/nthiery/16058-doc/combinat/index.html
+End result browsable at http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/index.html
One might argue that this reorganization of the documentation is not
consistent with what's done elsewhere in the manual. Indeed. I believeReplying to @nathanncohen:
The link toward the result is not availble anymore
Race-condition: I was precisely rebuilding it :-) The new link should work.
Replying to @nathanncohen:
Oh. By the equivalent
__init__.py. Nevermind:-P
Another race condition :-)
Yooooooooo !
On the bright side, this ticket intends to do so many things
requiring the input of so many persons that you can safely assume it
will ... take time before anything is done:-PBe my guest and show the example by doing your share :-)
Ahahah. Big political tickets are not my style, sorry. I change the things I know, bit by bit :-P
The produced documentation for the sections about graphs and designs
with this branched applied can be found respectively in:
Thanks ! Well, it looks cool, I mean... The design page looks exactly like it looks without your patch applied, so it's all good to me.
I am of course against having a "Graph" entry in combinat's doc. It just does not belong there, and it is not because combinat users may need other features of Sage that you should copy/paste their doc in your own document. If you can't be convinced otherwise, however, it would be better to redirect them toward the index of the graph help, i.e. this page :
http://www.sagemath.org/doc/reference/graphs/index.html
They would get what they asked for: the part of the doc dedicated to graphs.
- Checking that it looks good from the user point of view
The main page looks okay. The entries in the main combinat page may be sorted (Algebraic Combinatorics appears toward the end of the list)
Given that you do not have so many entries in "Thematic indexes", you could merge it with Dynamical Systems and Miscellaneous too.
It would avoid having a Miscellaneous entry in the Miscellaneous section too.
On the other hand, as soon as you click on the entries of the main page things begin to get messy. You can reach Words by its entry on the main page, and through "Enumerated sets and combinatorial objects"
Many entries only display the name of a class rather than a full-text description, as the all files you add do not necessarily have a module doc. Sooo well. Maybe you should first add at least one doc line to the top of each file in combinat before anything else.
- Choosing better entry points when appropriate
(e.g. sometime it's more natural to point directly to a class than
to the module defining it).- Checking that it looks natural from the dev point of view
It's better this way. The doc is closer to the code, that's nice.
Nathann
Branch pushed to git repo; I updated commit sha1. New commits:
eb78962 | 16256: reference graph theory, coding, and dynamics as 'related topics'; minor improvements |
Hi Nathann,
Thanks for looking this up and your comments!
Replying to @nathanncohen:
Thanks ! Well, it looks cool, I mean... The design page looks exactly like it looks without your patch applied, so it's all good to me.
:-)
I am of course against having a "Graph" entry in combinat's doc. It
just does not belong there, and it is not because combinat users may
need other features of Sage that you should copy/paste their doc in
your own document.
It's meant as a cross-reference, not as "include the doc here". I
clarified this by putting the link in a SEEALSO section.
The point of this cross ref is that a user interested in combinatorics
has some good chances to be interested in graph theory too. In
general, being able to easily add such crossrefs is actually one of my
big motivation for this ticket, as the lack of such crossrefs is one
of the weakest points of the reference manual.
it would be better to redirect them toward the index of the graph help, i.e. this page :
http://www.sagemath.org/doc/reference/graphs/index.html
They would get what they asked for: the part of the doc dedicated to graphs.
Good point. To achieve this, I allowed myself to add a label
"sage.graphs" at the top of doc/en/reference/graphs/index.rst.
The main page looks okay. The entries in the main combinat page may be sorted (Algebraic Combinatorics appears toward the end of the list)
Good point as well. I had tried to sort them semantically, but it's
actually so close from alphabetic order that it might as well be
alphabetic.
Given that you do not have so many entries in "Thematic indexes",
you could merge it with Dynamical Systems and Miscellaneous too.
Right. I had not noticed there was now a sage.dynamics folder. So I
cross-ref'd it instead, and added a link back from there to
e_one_star.
Vincent: tell me if that sounds good to you. Refactoring the index for
sage.dynamics as is done here for sage.combinat will probably
allow for a nicer looking crossref back; but I leave that to a later ticket.
It would avoid having a Miscellaneous entry in the Miscellaneous section too.
It's pretty ridiculous indeed. Not sure how to do this since that's
the title of the module, and given the content, I did not find a much
more compelling title.. Well, I renamed the section into "Utilities"
:-)
On the other hand, as soon as you click on the entries of the main
page things begin to get messy. You can reach Words by its entry on
the main page, and through "Enumerated sets and combinatorial
objects"
Yes, and this is on purpose: the organization of code according to a
tree layout is always somewhat arbitrary, whereas users looking for a
given feature may have different ideas in mind (you can come to words
by thinking "what objects can I enumerate through", or "word theory",
or "automata", or ...); so it's good that the given feature be
referenced from several places/indexes. Again I believe that's a
selling point for this ticket.
Many entries only display the name of a class rather than a
full-text description, as the all files you add do not necessarily
have a module doc. Sooo well. Maybe you should first add at least
one doc line to the top of each file in combinat before anything
else.
Yes, there is a technical sphinx point to investigate here.
In many cases, it's better to point directly to a class (or function)
instead of a module. This can be because the rest of the module
consists of not-so-interesting utility functions; or because a module
contains several classes that deserve to be highlighted; or because
the nice introductory documentation is written in the class.
Now, the question is: when referencing a class (or function), how to
display the one-line description of that class rather than its
name. Of course, one can always duplicate by hand that description,
but that's ugly.
As a first step, I have added a ~ so that at least we only see the
name of the class and not its module prefix. That does not look great
in the output in term of consistency of style, but I believe that's ok
for now and should not delay this ticket in case configuring Sphinx
turns out to take a bit of time.
It's better this way. The doc is closer to the code, that's nice.
Cool.
Cheers,
Nicolas
New commits:
b872e57 | 16256: use ~ when referencing classes and functions |
4ea19e8 | 16256: added title to sage.combinat.perm_grps.permutation_groups_catalog |
New commits:
b872e57 | 16256: use ~ when referencing classes and functions |
4ea19e8 | 16256: added title to sage.combinat.perm_grps.permutation_groups_catalog |
I think it would be a good idea to include crystals, root systems, symmetric functions etc in the thematic indexes. Also, what is the problems linking the thematic tutorials? The user should be able to access them from the front page.
Anne
Yoooooooooo !! (from my office at the LRI)
I am of course against having a "Graph" entry in combinat's doc. It
just does not belong there, and it is not because combinat users may
need other features of Sage that you should copy/paste their doc in
your own document.It's meant as a cross-reference, not as "include the doc here". I
clarified this by putting the link in a SEEALSO section.The point of this cross ref is that a user interested in combinatorics
has some good chances to be interested in graph theory too. In
general, being able to easily add such crossrefs is actually one of my
big motivation for this ticket, as the lack of such crossrefs is one
of the weakest points of the reference manual.
I wanted to give it a look but the doc does not compile with your branch. Several deprecation warnings appear at first, then there is this
OSError: [dynamics ] /home/ncohen/.Sage/src/doc/en/reference/dynamics/index.rst:14: WARNING: undefined label: sage.combinat.e_one_star (if the link has no caption the label must precede a section header)
I don't have anything against your fetishism for cross-references in general, though in this case you cannot exactly say that the doc for graphs is hard to find in Sage. It has its own entry in the first page of the reference manual :-P
This being said, you will find in the "graph" page a link toward the "IncidenceStructures" defined in combinat/designs, just in case a guy who needs a hypergraph class ends up there. But this is way harder to find than Graphs.
Many entries only display the name of a class rather than a
full-text description, as the all files you add do not necessarily
have a module doc. Sooo well. Maybe you should first add at least
one doc line to the top of each file in combinat before anything
else.Yes, there is a technical sphinx point to investigate here.
In many cases, it's better to point directly to a class (or function)
instead of a module. This can be because the rest of the module
consists of not-so-interesting utility functions; or because a module
contains several classes that deserve to be highlighted; or because
the nice introductory documentation is written in the class.
Well... I solved this the other way, by adding interesting doc in the module itself. While it's not very natural to look at the doc of a module when you use Sage, these pages are the html page that appear on google when you look for help. Sooooooo I guess that quite a lot of person end up reading them.
When the module consists of many "not very useful" functions and a few interesting things, you can chose to only mention the important function in the module's head, or to emphasize those that are actually useful.
http://www.sagemath.org/doc/reference/combinat/sage/combinat/designs/latin_squares.html
http://www.sagemath.org/doc/reference/combinat/sage/combinat/designs/incidence_structures.html
A couple of words, an index of functions, and you can point to the module directly.
See you later if you come to the lab !
Nathann
Oh. It seems that if you "try harder" the doc can be built:
make doc-clean && make # will not work
But
make doc-clean; make;make;make;make;make # should eventually work
When you build a module which refers to a module that has not been built the reference fails, but if you type "make" again the failed document will not be rebuilt, so the problem is skipped. With a bit of luck you will build the other document someday, and THEN you will be able to build the first.
Anyway, this may be a problem, at least for Volker.
Nathann
Replying to @nathanncohen:
Oh. It seems that if you "try harder" the doc can be built:
make doc-clean && make # will not workBut
make doc-clean; make;make;make;make;make # should eventually work
Yes, sorry, I got also bitten by this and was actually about to put a
warning about this on the ticket. We investigated this a bit this
morning with Florent, and it's likely to be just a glitch in the
warning reporting while in the first pass of the compilation. This
definitely has to be fixed before this ticket can go in.
I'll come to the lab tomorrow. Today I am handling teaching
organization in the vallée ...
Cheers,
Nicolas
Description changed:
---
+++
@@ -20,11 +20,20 @@
- Fixed some documentation syntax glitches here and there
- Added the catalogs of permutation groups and matrix groups to the
- reference manual so that we can link to them.
+ reference manual so that we can link to them. Fixed the doc title of
+ the former.
+
+- Added a back link from the doc of sage.dynamics
- Added (draft of) sage.combinat.quickref
+This is a follow up to #16058.
+
End result browsable at http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/index.html
+
+Warning: see the note below about the current doc compilation glitch.
+
+*Discussion*
One might argue that this reorganization of the documentation is not
consistent with what's done elsewhere in the manual. Indeed. I believe
@@ -63,8 +72,9 @@
- one can point to related things elsewhere in the source code
-TODO:
+*TODO*
+- Sphinx issue to be investigated: currently `make doc` fails upon
- confirm that this is the right approach
- proof reading
@@ -73,12 +83,22 @@
- checking that the links are functional
-- deciding on how to link to classes/functions: in the index we would
- want to have the title of the documentation of the class rather than
- the name of the class; or maybe both.
-
- here or in a later ticket: finish automatizing the building of
module_list.rst.
-This is a follow up to #16058.
+ first attempt, complaining about a broken link. One need to rerun
+ it, and then the link is failed. This is probably just a glitch in
+ how warnings are reported during the first pass of the reference
+ manual compilation, but needs to be fixed before this ticket goes
+ in.
+- Sphinx issue to be investigated: deciding on how to link to
+ classes/functions: in the index we would want to have the title of
+ the documentation of the class rather than the name of the class; or
+ maybe both. It might be ok to stick to the class name for now until
+ we find a good way to do this with Sphinx.
+
+- Sphinx issue to be investigated: how to crossrefs documents in the
+ thematic tutorial. If there is no immediate way, it's possible to
+ make a workaround for now.
+Description changed:
---
+++
@@ -33,7 +33,7 @@
Warning: see the note below about the current doc compilation glitch.
-*Discussion*
+=Discussion=
One might argue that this reorganization of the documentation is not
consistent with what's done elsewhere in the manual. Indeed. I believe
@@ -72,7 +72,7 @@
- one can point to related things elsewhere in the source code
-*TODO*
+=TODO=
- Sphinx issue to be investigated: currently `make doc` fails upon
- confirm that this is the right approachHi Anne!
Thanks for looking!
Replying to @anneschilling:
I think it would be a good idea to include crystals, root systems, symmetric functions etc in the thematic indexes.
Ok, will do then!
Also, what is the problems linking the thematic tutorials? The user should be able to access them from the front page.
Just a sphinx issue for how to generate properly the link (the reference manual is built before the thematic tutorials, so can't access its intersphinx database of labels). I'll investigate this with Florent, but we can always workaround this for now with a hardcoded html link.
Cheers,
Nicolas
Branch pushed to git repo; I updated commit sha1. New commits:
3f0ef5a | 16256: ReST typo fix on previous commit |
Hi!
Here are some brief comments:
-
In http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/sage/combinat/quickref.html#sage-combinat-quickref the syntax does not seem right for some of the entries. Perhaps this part is still unfinished. I would suggest to also add Tableaux (with usual and some affine versions), Cores (perhaps close to Partitions) and Permutations (perhaps close to WeylGroups and RootSystems).
-
The title "Bases for ." in "Symmetric Functions in Non-Commuting Variables" looks weird.
-
I am not sure why all these catalogs are
Catalog Of Crystals
Catalog Of Elementary Crystals
Catalog Of Crystal Models For
Catalog Of Crystal Models For Kirillov-Reshetikhin Crystals
are listed separately. The third title seems to be missing something. In principle the last three are subsumed under the link "Catalog Of Crystals".
-
The link under "Introductory material" for crystals "Crystals – This overview" is broken.
-
In general, math displays seem to be missing from titles which make them look strange and incomplete.
-
The alphabetical module list does not seem to be alphabetical.
Best,
Anne
Description changed:
---
+++
@@ -1,4 +1,4 @@
-Reorganize the documentation indexes into src/sage/combinat:
+## Goal: reorganize the documentation indexes into src/sage/combinat
- For example, the thematic index
`src/doc/en/reference/combinat/crystals.rst` is now in:
@@ -33,7 +33,7 @@
Warning: see the note below about the current doc compilation glitch.
-=Discussion=
+## Discussion
One might argue that this reorganization of the documentation is not
consistent with what's done elsewhere in the manual. Indeed. I believe
@@ -72,9 +72,10 @@
- one can point to related things elsewhere in the source code
-=TODO=
+## TODO
-- Sphinx issue to be investigated: currently `make doc` fails upon
+- Sphinx issue to be investigated: currently `make doc` fails upon the first pass of the compilation of the reference manual, complaining about missing link for `sage.coding`. Reruning `make doc` solves the problem.
+
- confirm that this is the right approach
- proof readingBranch pushed to git repo; I updated commit sha1. New commits:
2252c44 | 16256: improved sage.combinat.crystals's index |
Replying to @anneschilling:
Here are some brief comments:
Thanks!
- In http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/sage/combinat/quickref.html#sage-combinat-quickref the syntax does not seem right for some of the entries.
All tests pass now :-)
I would suggest to also add Tableaux (with usual and some affine versions), Cores (perhaps close to Partitions) and Permutations (perhaps close to WeylGroups and RootSystems).
Good point: I have added examples with permutations, tableaux,
dyckwords, trees. I left out affine tableaux and cores for now, as
they seem sound to me a bit exotic for a general combinatorics
quickref. They definitely would make sense in a more specialized
quickref though.
What do you think?
- I am not sure why all these catalogs are
Catalog Of Crystals Catalog Of Elementary Crystals Catalog Of Crystal Models For Catalog Of Crystal Models For Kirillov-Reshetikhin Crystalsare listed separately. The third title seems to be missing something. In principle the last three are subsumed under the link "Catalog Of Crystals".
Good point. I removed them.
By the way: what about removing the definition of crystals from
sage.combinat.crystals.catalog? It duplicates that of
sage.combinat.crystals.crystals, and the user interested just in the
catalog needs to scroll down.
- The title "Bases for ." in "Symmetric Functions in Non-Commuting Variables" looks weird.
- In general, math displays seem to be missing from titles which make them look strange and incomplete.
Indeed: sphinx does not handle math in (references to) titles. Since
this was already broken beforehand, I was thinking of not fixing this
in this ticket to avoid being too invasive. Now, if you give me a
green light for crystals, I can fix those. Idem for the above change
to the catalog.
- The link under "Introductory material" for crystals "Crystals – This overview" is broken.
Fixed. More precisely work around (the usual issue with linking to the
thematic tutorials).
- The alphabetical module list does not seem to be alphabetical.
It's alphabetical in term of module names, but not module titles. Not
sure what's the best approach here; possibly including the name of the
module.
Cheers,
Nicolas
New commits:
8602a2d | 16256: pass of proofreading on all combinat documentation indexes, handling a bunch of TODO's there. |
7af0a5d | 16256: improved sage.combinat.quickref |
2252c44 | 16256: improved sage.combinat.crystals's index |
I have taken care of a bunch of the TODO's. The other could possibly be taken care later on since they are anyway further enhancements w.r.t. the previous state. The big remaining thing are the Sphinx technicalities.
I am putting this to needs review to get the buildbot to munch on it.
Changed work issues from gather comments by showing it around, and work on the listed TODO's to Fix sphinx issues.
Description changed:
---
+++
@@ -74,24 +74,29 @@
## TODO
-- Sphinx issue to be investigated: currently `make doc` fails upon the first pass of the compilation of the reference manual, complaining about missing link for `sage.coding`. Reruning `make doc` solves the problem.
+- Confirm that this is the right approach
-- confirm that this is the right approach
+- Proof reading
-- proof reading
+- Checking that the links are functional
-- choosing the right entry points for each module
+- Handle the various TODO's left in the indexes (typically about
+ choosing the right entry points for each module)
-- checking that the links are functional
+ Could be postponed to a later ticket, since those are further
+ enhancements not directly related to this ticket. It's just that,
+ while browsing through the indexes suggested them to me.
-- here or in a later ticket: finish automatizing the building of
- module_list.rst.
+- Finish automatizing the building of module_list.rst.
- first attempt, complaining about a broken link. One need to rerun
- it, and then the link is failed. This is probably just a glitch in
- how warnings are reported during the first pass of the reference
- manual compilation, but needs to be fixed before this ticket goes
- in.
+ Could be postponed to a later ticket.
+
+- Sphinx issue to be investigated: currently `make doc` fails upon the
+ first attempt, complaining about a broken link for
+ `sage.coding`. One need to rerun it, and then the link is
+ failed. This is probably just a glitch in how warnings are reported
+ during the first pass of the reference manual compilation, but needs
+ to be fixed before this ticket goes in.
- Sphinx issue to be investigated: deciding on how to link to
classes/functions: in the index we would want to have the title of
@@ -100,6 +105,5 @@
we find a good way to do this with Sphinx.
- Sphinx issue to be investigated: how to crossrefs documents in the
- thematic tutorial. If there is no immediate way, it's possible to
- make a workaround for now.
+ thematic tutorial. For now we use a workaround.
- In http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/sage/combinat/quickref.html#sage-combinat-quickref the syntax does not seem right for some of the entries.
All tests pass now :-)
That is surprising given some of the syntax
sage: CoxeterGroup(["B",3]).some_flashy_feature()
or
sage: M = MultivariatePolynomials('x0,x1,x2,x3')
sage: M(...).action??? S.
Good point: I have added examples with permutations, tableaux,
dyckwords, trees. I left out affine tableaux and cores for now, as
they seem sound to me a bit exotic for a general combinatorics
quickref. They definitely would make sense in a more specialized
quickref though.What do you think?
That looks good!
- I am not sure why all these catalogs are
Catalog Of Crystals Catalog Of Elementary Crystals Catalog Of Crystal Models For Catalog Of Crystal Models For Kirillov-Reshetikhin Crystalsare listed separately. The third title seems to be missing something. In principle the last three are subsumed under the link "Catalog Of Crystals".
Good point. I removed them.
Perhaps I am looking at an old version of the compiled documentation, but on
http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/sage/combinat/crystals/__init__.html#sage-combinat-crystals
they are still there.
By the way: what about removing the definition of crystals from
sage.combinat.crystals.catalog? It duplicates that of
sage.combinat.crystals.crystals, and the user interested just in the
catalog needs to scroll down.
Unlike stated on the catalogue site, the documentation does not completely duplicate the documentation in sage.combinat.crystals.crystals. I suggest moving it to sage.combinat.crystals.crystals.
This link
http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/sage/combinat/crystals/__init__.html#sage-combinat-crystals
on the crystal quickref site seems to be broken.
The link to sage.combinat.posets on
http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/sage/combinat/quickref.html
seems to be broken.
Indeed: sphinx does not handle math in (references to) titles. Since
this was already broken beforehand, I was thinking of not fixing this
in this ticket to avoid being too invasive. Now, if you give me a
green light for crystals, I can fix those. Idem for the above change
to the catalog.
Sure.
- The link under "Introductory material" for crystals "Crystals – This overview" is broken.
Fixed. More precisely work around (the usual issue with linking to the
thematic tutorials).
For me that link is still broken. I am confused (since you say it is supposed to be the link to the thematic tutorial): That link appear two lines below that under
"The Lie Methods and Related Combinatorics thematic tutorial"
Why have two links to the thematic tutorial?
- The alphabetical module list does not seem to be alphabetical.
It's alphabetical in term of module names, but not module titles. Not
sure what's the best approach here; possibly including the name of the
module.
That is very confusing to the user and developer since it says explicitly "alphabetical". From just looking at the list, it is not clear that the modules are listed alphabetical. Please include the name of the module or not flatten the list.
Best,
Anne
Replying to @anneschilling:
That is surprising given some of the syntax
...
Perhaps I am looking at an old version of the compiled documentation, but on
http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/sage/combinat/crystals/__init__.html#sage-combinat-crystals
they are still there.
... various broken links ...
Sorry, I screwed up the rsync. Ok, now it's scripted, so that I don't
screw up again next time.
Unlike stated on the catalogue site, the documentation does not completely duplicate the documentation in sage.combinat.crystals.crystals. I suggest moving it to sage.combinat.crystals.crystals.
Sure.
Ok, will do! When I find the time ...
For me that link is still broken. I am confused (since you say it is supposed to be the link to the thematic tutorial): That link appear two lines below that under
"The Lie Methods and Related Combinatorics thematic tutorial"
Why have two links to the thematic tutorial?
The first points to the introduction in
sage.combinat.crystals.crystals, the second one to the thematic
tutorial.
That is very confusing to the user and developer since it says
explicitly "alphabetical". From just looking at the list, it is not
clear that the modules are listed alphabetical. Please include the
name of the module or not flatten the list.
Hmm, more sphinx to do ...
Cheers,
Nicolas
Branch pushed to git repo; I updated commit sha1. New commits:
d4b6d28 | 16256: merged the two introduction of crystals (in the catalog.py an crystals.py) and further little improvements |
Branch pushed to git repo; I updated commit sha1. New commits:
2872210 | 16256: proofreading previous commit |
Anne, are you happy with the latest version (except it seems it needs rebasing)?
It would be very nice to get this merged!
It would be cool to have an updated branch first to be able to see all accumulated changes on the trac ticket.
Nathann
Replying to @jpflori:
Anne, are you happy with the latest version (except it seems it needs rebasing)?
It would be very nice to get this merged!
From the comments above it seems like Nicolas has not yet made all the changes. It is not possible to look at the branch right now, so I cannot comment more.
Anne
Have fun.
Changed branch from u/nthiery/reorganize_the_documentation_indexes_into_src_sage_combinat to u/jpflori/16256
Last 10 new commits:
4ea19e8 | 16256: added title to sage.combinat.perm_grps.permutation_groups_catalog |
7b66375 | 16256: temporarily hard coded html links to the thematic tutorials |
29734cf | 16256: added direct links to the indexes on crystals, quiver algebras, root systems, ... |
3f0ef5a | 16256: ReST typo fix on previous commit |
8602a2d | 16256: pass of proofreading on all combinat documentation indexes, handling a bunch of TODO's there. |
7af0a5d | 16256: improved sage.combinat.quickref |
2252c44 | 16256: improved sage.combinat.crystals's index |
d4b6d28 | 16256: merged the two introduction of crystals (in the catalog.py an crystals.py) and further little improvements |
2872210 | 16256: proofreading previous commit |
28969d7 | Merge remote-tracking branch 'trac/develop' into ticket/16256 |
Changed branch from u/jpflori/16256 to u/jpflori/ticket/16256
This is incorrect, at least for combinatorial designs.
Nathann
This is not very helpful.
What is incorrect?
What the ticket removes from the current file is not what is being added into the new one.
My 2 cents, I liked having the specific Cartan type data in a separate file to not clutter or distract.
Also a catalog for algebras is #16219.
Thanks for your interest, feedback, and work. At this point, the blocker is the Sphinx compilation issue with crosslinks, and I am stuck there. Once this is taken care of (Florent, please!!!), finalizing the rebase upon the latest beta will be a breeze.
Cheers,
Nicolas
I worked with Florent this afternoon on a fix for #17189 which I created for the Sphinx compilation issue.
Changed branch from u/jpflori/ticket/16256 to u/nthiery/ticket/16256
Replying to @tscrim:
My 2 cents, I liked having the specific Cartan type data in a separate file to not clutter or
distract.
Good question. It's at the end, and it gives at a glance an overview of how things are organized. Also, I would not know where to split (e.g. where to put the semi generic stuff like type_affine, type_dual). So at this point I vote for keeping things as they are. And if the file grows further, or many more types are added (e.g. for complex reflection groups), then we will split that off.
Also a catalog for algebras is #16219.
Thanks for the pointer and for that catalog! I reviewed it, and will merge it in as a dependency as soon as it's finalized.
New commits:
b7e0a69 | 17189: upon the first pass of the documentation compilation, warnings don't trigger an exception |
fb43b19 | 17189: referee's suggestions: only undefined warnings don't trigger an exception |
eaff50b | 16256: Merge branch 't/17189/upon_the_first_pass_of_the_documentation_compilation__undefined_label_warnings_should_not_trigger_an_exception' |
cef0ee0 | 16256: fixed missing links from the previous merge |
Changed work issues from Fix sphinx issues. to none
Description changed:
---
+++
@@ -74,8 +74,6 @@
## TODO
-- Confirm that this is the right approach
-
- Proof reading
- Checking that the links are functional
@@ -83,27 +81,24 @@
- Handle the various TODO's left in the indexes (typically about
choosing the right entry points for each module)
- Could be postponed to a later ticket, since those are further
- enhancements not directly related to this ticket. It's just that,
- while browsing through the indexes suggested them to me.
+ Postponed to a later ticket, since those are further enhancements
+ not directly related to this ticket. It's just that, while browsing
+ through the indexes suggested them to me.
- Finish automatizing the building of module_list.rst.
- Could be postponed to a later ticket.
-
-- Sphinx issue to be investigated: currently `make doc` fails upon the
- first attempt, complaining about a broken link for
- `sage.coding`. One need to rerun it, and then the link is
- failed. This is probably just a glitch in how warnings are reported
- during the first pass of the reference manual compilation, but needs
- to be fixed before this ticket goes in.
+ Postponed to a later ticket.
- Sphinx issue to be investigated: deciding on how to link to
classes/functions: in the index we would want to have the title of
the documentation of the class rather than the name of the class; or
- maybe both. It might be ok to stick to the class name for now until
- we find a good way to do this with Sphinx.
+ maybe both.
+
+ For now, we stick to the class name for now until we find a good way
+ to do this with Sphinx.
- Sphinx issue to be investigated: how to crossrefs documents in the
- thematic tutorial. For now we use a workaround.
+ thematic tutorial.
+ For now we use a workaround.
+For the record: the doc compiles, and all long tests pass but for one easy failure:
Failed example:
sage.misc.dev_tools.load_submodules(sage.combinat)
Expected:
load sage.combinat.cluster_algebra_quiver.cluster_seed... suceeded
load sage.combinat.cluster_algebra_quiver.mutation_class... suceeded
...
load sage.combinat.words.suffix_trees... suceeded
Remains to double check the doc building with -warn-links.
Some quick comments that I think should really be fixed:
- The alphabetical module list is not alphabetical
- Some links to thematic tutorials are broken (perhaps you did not put them on the website?).
Anne
On a related note, would third-party links still work with this reorganization? (Similarly to something we had to do with the change in the Sage reference manual to build in parallel.) My apologies if this is addressed somewhere above, I didn't find it on a quick glance.
Replying to @kcrisman:
On a related note, would third-party links still work with this reorganization? (Similarly to something we had to do with the change in the Sage reference manual to build in parallel.) My apologies if this is addressed somewhere above, I didn't find it on a quick glance.
You mean cross links between different documents of the reference manual? Yes indeed; actually the reorganization encourages such links.
As for other links, it should not make a difference.
Replying to @anneschilling:
Some quick comments that I think should really be fixed:
- The alphabetical module list is not alphabetical
That's how ls sorts stuff, I don't think that's a terrible choice.
Is it the way capitals and underscores are dealt with that you don't like?
This can be easily changed.
- Some links to thematic tutorials are broken (perhaps you did not put them on the website?).
Which ones?
Replying to @jpflori:
Replying to @anneschilling:
Some quick comments that I think should really be fixed:
- The alphabetical module list is not alphabetical
That's how
lssorts stuff, I don't think that's a terrible choice.
Is it the way capitals and underscores are dealt with that you don't like?
This can be easily changed.
Oh, I see, what is in the doc is not in alphabetical order indeed...
Only what is in the file used to generate the doc.
- Some links to thematic tutorials are broken (perhaps you did not put them on the website?).
Which ones?
Replying to @jpflori:
Replying to @jpflori:
Replying to @anneschilling:
Some quick comments that I think should really be fixed:
- The alphabetical module list is not alphabetical
That's how
lssorts stuff, I don't think that's a terrible choice.
Is it the way capitals and underscores are dealt with that you don't like?
This can be easily changed.Oh, I see, what is in the doc is not in alphabetical order indeed...
Only what is in the file used to generate the doc.
- Some links to thematic tutorials are broken (perhaps you did not put them on the website?).
Which ones?
Were you thinking about these ones:
Replying to @nthiery:
For the record: the doc compiles, and all long tests pass but for one easy failure:
Failed example: sage.misc.dev_tools.load_submodules(sage.combinat) Expected: load sage.combinat.cluster_algebra_quiver.cluster_seed... suceeded load sage.combinat.cluster_algebra_quiver.mutation_class... suceeded ... load sage.combinat.words.suffix_trees... suceededRemains to double check the doc building with
-warn-links.
Is there any easy way to do this for the combinat folder only?
And I guess --warn-links must only be passed in the second pass?
Replying to @jpflori:
Replying to @jpflori:
Replying to @anneschilling:
Some quick comments that I think should really be fixed:
- The alphabetical module list is not alphabetical
That's how
lssorts stuff, I don't think that's a terrible choice.
Is it the way capitals and underscores are dealt with that you don't like?
This can be easily changed.Oh, I see, what is in the doc is not in alphabetical order indeed...
Only what is in the file used to generate the doc.
So this will be more involved, I guess doing it properly would involved asking shpinx what it intends to use for each file and sort afterward.
- Some links to thematic tutorials are broken (perhaps you did not put them on the website?).
Which ones?
Replying to @jpflori:
Replying to @anneschilling:
Some quick comments that I think should really be fixed:
- The alphabetical module list is not alphabetical
That's how
lssorts stuff, I don't think that's a terrible choice.
Is it the way capitals and underscores are dealt with that you don't like?
This can be easily changed.
I found it confusing that it says on the top that the list is in alphabetical order, but then it is not. Since a user won't know what kind of sort is used, it is hard to guess (unless it is explained how the sort is done).
- Some links to thematic tutorials are broken (perhaps you did not put them on the website?).
Which ones?
For example the link to the "Lie Tutorial" on
http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/sage/combinat/crystals/__init__.html#sage-combinat-crystals