#16256: Reorganize the documentation indexes into src/sage/combinat
-------------------------------------+-------------------------------------
Reporter: nthiery | Owner:
Type: enhancement | Status: needs_info
Priority: major | Milestone: sage-6.4
Component: documentation | Resolution:
Keywords: combinatorics, | Merged in:
thematic index, quickref | Reviewers:
Authors: Nicolas M. Thiéry | Work issues: gather comments by
Report Upstream: N/A | showing it around, and work on the
Branch: | listed TODO's
u/nthiery/reorganize_the_documentation_indexes_into_src_sage_combinat|
Commit:
Dependencies: #16058 | 4ea19e8e8c4b00e9c64247b49fa4ce55c55647b8
| Stopgaps:
-------------------------------------+-------------------------------------
Comment (by nthiery):
Hi Nathann,
Thanks for looking this up and your comments!
Replying to [comment:31 ncohen]:
> 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:
||[http://git.sagemath.org/sage.git/commit/?id=b872e5754a9ea0b33363b1bb5ed2bb52573da400
b872e57]||{{{16256: use ~ when referencing classes and functions}}}||
||[http://git.sagemath.org/sage.git/commit/?id=4ea19e8e8c4b00e9c64247b49fa4ce55c55647b8
4ea19e8]||{{{16256: added title to
sage.combinat.perm_grps.permutation_groups_catalog}}}||
----
New commits:
||[http://git.sagemath.org/sage.git/commit/?id=b872e5754a9ea0b33363b1bb5ed2bb52573da400
b872e57]||{{{16256: use ~ when referencing classes and functions}}}||
||[http://git.sagemath.org/sage.git/commit/?id=4ea19e8e8c4b00e9c64247b49fa4ce55c55647b8
4ea19e8]||{{{16256: added title to
sage.combinat.perm_grps.permutation_groups_catalog}}}||
--
Ticket URL: <http://trac.sagemath.org/ticket/16256#comment:34>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/d/optout.
