search

sagemath / sage

Main repository of SageMath
https://www.sagemath.org
Other
1.45k stars 482 forks source link

Documentation and list of Graph functions #12816

Closed 6bdad4c1-1e26-4f2f-a442-a01a2292c181 closed 12 years ago

6bdad4c1-1e26-4f2f-a442-a01a2292c181 commented 12 years ago

This patch only touches documentation. It mainly adds lists of function to the top of important Graph files so that we can, at long long long last, see what on earth those objects can do. This list will have to be maintained manually, so this is a bad solution to a problem that should be fixed by Sphinx. Only it is not, and we really need to have such lists !

Apply:

Nathann

Depends on #12743 Depends on #12903

CC: @dcoudert

Component: graph theory

Author: Nathann Cohen

Reviewer: David Coudert

Merged: sage-5.1.beta1

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

dcoudert commented 12 years ago
comment:2

The patch passes successfully a sage -t --long -force_lib --verbose sage/graphs test, and the doc builds properly. The result is really nice.

Clearly, it would be nice to have such sections on top of all pages.

For graph colorings, you have organized the methods by type. What about organizing methods by type in graph.py, generic_graph.py, etc. ?

I like this patch.

dcoudert commented 12 years ago

Reviewer: David Coudert

6bdad4c1-1e26-4f2f-a442-a01a2292c181 commented 12 years ago
comment:4

Done here ! But I would really like to get a good answer from the Sphinx guys, for the html file produced really is awful :-p

https://groups.google.com/d/topic/sphinx-dev/GWLtoAHGOo4/discussion

Nathann

dcoudert commented 12 years ago
comment:5

In the produced html files, you can see that:

Unfortunately, I don't think sphinx allows for adding such directive :(

This is exactly the same story with the other type of tables (+----------+---------+).

dcoudert commented 12 years ago
comment:6

A better solution is to use csv-table (http://docutils.sourceforge.net/docs/ref/rst/directives.html#table). Bellow is an example for graph.py

**Graph basic operations:** 

.. csv-table:: 
    :class: contentstable 
    :header: "Methods", "Description" 
    :widths: 50, 50 
    :delim: | 

    :meth:`~Graph.write_to_eps` | Writes a plot of the graph to ``filename`` in ``eps`` format. 
    :meth:`~Graph.to_undirected` | Since the graph is already undirected, simply returns a copy of itself. 
    :meth:`~Graph.to_directed` | Returns a directed version of the graph. 
    :meth:`~Graph.sparse6_string` | Returns the sparse6 representation of the graph as an ASCII string. 
    :meth:`~Graph.graph6_string` | Returns the graph6 representation of the graph as an ASCII string. 
    :meth:`~Graph.bipartite_sets` | Returns `(X,Y)` where X and Y are the nodes in each bipartite set of graph. 
    :meth:`~Graph.bipartite_color` | Returns a dictionary with vertices as the keys and the color class as the values. 
    :meth:`~Graph.is_directed` | Since graph is undirected, returns False. 

**Distances:** 

.. csv-table:: 
    :class: contentstable 
    :header: "Methods", "Description" 
    :widths: 50, 50 
    :delim: | 

    :meth:`~Graph.centrality_closeness` | Returns the closeness centrality (1/average distance to all vertices) 
    :meth:`~Graph.centrality_degree` | Returns the degree centrality 
    :meth:`~Graph.centrality_betweenness` | Returns the betweenness centrality 

**Graph properties:** 

.. csv-table:: 
    :class: contentstable 
    :header: "Methods", "Description" 
    :widths: 50, 50 
    :delim: | 

    :meth:`~Graph.is_prime` | Tests whether the current graph is prime. 
    :meth:`~Graph.is_split` | Returns ``True`` if the graph is a Split graph, ``False`` otherwise. 
    :meth:`~Graph.is_triangle_free` | Returns whether ``self`` is triangle-free 
    :meth:`~Graph.is_bipartite` | Returns True if graph G is bipartite, False if not. 
    :meth:`~Graph.is_line_graph` | Tests wether the graph is a line graph. 
    :meth:`~Graph.is_odd_hole_free` | Tests whether ``self`` contains an induced odd hole. 
    :meth:`~Graph.is_even_hole_free` | Tests whether ``self`` contains an induced even hole.

The output is better, but we have another issue to solve.

In the original graph.html file produced when building the documentation, we have: