#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 ncohen):
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
--
Ticket URL: <http://trac.sagemath.org/ticket/16256#comment:36>
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.
