#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 | a23c12fafb58d03e371d47102bc490a7142ab7ab
| Stopgaps:
-------------------------------------+-------------------------------------
Comment (by ncohen):
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 `:-P`
>
> Be 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
--
Ticket URL: <http://trac.sagemath.org/ticket/16256#comment:31>
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.
