Ticket #13862: trac_13862-doc.patch

File trac_13862-doc.patch, 17.0 KB (added by ncohen, 7 years ago)
  • sage/graphs/graph_generators.py

    # HG changeset patch
    # User Nathann Cohen <nathann.cohen@gmail.com>
    # Date 1356520466 -3600
    # Node ID 1caeed35bcfb1376ba784b3c95ce248fae4a7e3a
    # Parent  26888271190874dc42f9ce0bd45a6e6995eb1e77
    Split graph_generators into several files -- doc rewrite, first part
    
    diff --git a/sage/graphs/graph_generators.py b/sage/graphs/graph_generators.py
    a b  
    22r"""
    33Common graphs
    44
    5 Usage
    6 =====
     5All graphs in Sage can be built through the ``graphs`` object : in order to
     6build a complete graph on `15` elements, one can do::
    77
    8 To see a list of all graph constructors, type "graphs." and then
    9 press the tab key. The documentation for each constructor includes
    10 information about each graph, which provides a useful reference.
     8    sage: g = graphs.CompleteGraph(15)
    119
     10More interestingly, one can get the list of all graphs that Sage knows how to
     11buid by typing ``graphs.`` in Sage, then hitting tab.
     12"""
    1213
    13 Plotting
    14 ========
     14# This method appends a list of methods to the doc as a 3xN table.
    1515
    16 All graphs (i.e., networks) have an associated Sage
    17 graphics object, which you can display::
     16# Here's the point :
     17#
     18# we just have to insert the method's name in this file to add it to
     19# the tab, and in exchange the doc contains a table of width 3 with
     20# all methods listed, so that the reading order is Column1, then
     21# Column2, then Column3. Doing this by hand is hell with Sphinx when
     22# you need to insert a new method inside of the list !
    1823
    19     sage: G = graphs.WheelGraph(15)
    20     sage: P = G.plot()
    21     sage: P.show() # long time
     24def __append_to_doc(methods):
     25    global __doc__
     26    __doc__ += ("\n.. csv-table::\n"
     27    "    :class: contentstable\n"
     28    "    :widths: 33, 33, 33\n"
     29    "    :delim: |\n\n")
    2230
    23 If you create a graph in Sage using the ``Graph``
    24 command, then plot that graph, the positioning of nodes is
    25 determined using the spring-layout algorithm. For the special graph
    26 constructors, which you get using ``graphs.[tab]``, the
    27 positions are preset. For example, consider the Petersen graph with
    28 default node positioning vs. the Petersen graph constructed by this
    29 database::
     31    h = (len(methods)+2)//3
     32    # Reorders the list of methods for horizontal reading, the only one Sphinx understands
     33    reordered_methods = [0]*3*h
     34    for i, m in enumerate(methods):
     35        reordered_methods[3*(i%h)+(i//h)] = m
     36    methods = reordered_methods
    3037
    31     sage: petersen_spring = Graph({0:[1,4,5], 1:[0,2,6], 2:[1,3,7], 3:[2,4,8], 4:[0,3,9], 5:[0,7,8], 6:[1,8,9], 7:[2,5,9], 8:[3,5,6], 9:[4,6,7]})
    32     sage: petersen_spring.show() # long time
    33     sage: petersen_database = graphs.PetersenGraph()
    34     sage: petersen_database.show() # long time
     38    # Adding the list to the __doc__ string
     39    wrap_name = lambda x : ":meth:`"+str(x)+" <GraphGenerators."+str(x)+">`" if x else ""
     40    while methods:
     41        a = methods.pop(0)
     42        b = methods.pop(0)
     43        c = methods.pop(0)
     44        __doc__ += "    "+wrap_name(a)+" | "+wrap_name(b)+" | "+wrap_name(c)+"\n"
    3545
    36 For all the constructors in this database (except the octahedral,
    37 dodecahedral, random and empty graphs), the position dictionary is
    38 filled in, instead of using the spring-layout algorithm.
     46__doc__ += """
     47**Basic structures**
     48"""
    3949
    40 For further visual examples and explanation, see the docstrings
    41 below, particularly for
    42 :meth:`CycleGraph <GraphGenerators.CycleGraph>`,
    43 :meth:`StarGraph <GraphGenerators.StarGraph>`,
    44 :meth:`WheelGraph <GraphGenerators.WheelGraph>`,
    45 :meth:`CompleteGraph <GraphGenerators.CompleteGraph>`, and
    46 :meth:`CompleteBipartiteGraph <GraphGenerators.CompleteBipartiteGraph>`.
     50__append_to_doc(
     51    ["BarbellGraph",
     52     "BuckyBall",
     53     "BullGraph",
     54     "ButterflyGraph",
     55     "CircularLadderGraph",
     56     "ClawGraph",
     57     "CycleGraph",
     58     "DiamondGraph",
     59     "EmptyGraph",
     60     "Grid2dGraph",
     61     "GridGraph",
     62     "HouseGraph",
     63     "HouseXGraph",
     64     "KrackhardtKiteGraph",
     65     "LadderGraph",
     66     "LollipopGraph",
     67     "PathGraph",
     68     "StarGraph",
     69     "ToroidalGrid2dGraph",
     70     "Toroidal6RegularGrid2dGraph",
     71     "WheelGraph"]
     72    )
    4773
    48 .. _organization:
     74__doc__ += """
     75**Platonic solids**
     76"""
    4977
    50 Organization
    51 ============
     78__append_to_doc(["DodecahedralGraph",
     79"HexahedralGraph",
     80"IcosahedralGraph",
     81"OctahedralGraph",
     82"TetrahedralGraph"])
    5283
    53 The constructors available in this database are
    54 organized as follows.
     84__doc__ += """
     85**Small Graphs**
     86"""
    5587
    56 Basic structures
    57 ----------------
     88__append_to_doc(
     89    ["Balaban10Cage",
     90     "Balaban11Cage",
     91     "BidiakisCube",
     92     "BiggsSmithGraph",
     93     "BrinkmannGraph",
     94     "ChvatalGraph",
     95     "ClebschGraph",
     96     "CoxeterGraph",
     97     "DoubleStarSnark",
     98     "DesarguesGraph",
     99     "DurerGraph",
     100     "DyckGraph",
     101     "EllinghamHorton54Graph",
     102     "EllinghamHorton78Graph",
     103     "ErreraGraph",
     104     "FlowerSnark",
     105     "FosterGraph",
     106     "FranklinGraph",
     107     "FruchtGraph",
     108     "GoldnerHararyGraph",
     109     "GrayGraph",
     110     "GrotzschGraph",
     111     "HallJankoGraph",
     112     "HararyGraph",
     113     "HarriesGraph",
     114     "HarriesWongGraph",
     115     "HeawoodGraph",
     116     "HerschelGraph",
     117     "HigmanSimsGraph",
     118     "HoffmanSingletonGraph",
     119     "HoffmanGraph",
     120     "HoltGraph",
     121     "LjubljanaGraph",
     122     "McGeeGraph",
     123     "MoebiusKantorGraph",
     124     "MoserSpindle",
     125     "NauruGraph",
     126     "PappusGraph",
     127     "PetersenGraph",
     128     "ShrikhandeGraph",
     129     "ThomsenGraph",
     130     "Tutte12Cage",
     131     "TutteCoxeterGraph",
     132     "WagnerGraph"])
    58133
    59 - :meth:`BarbellGraph <GraphGenerators.BarbellGraph>`
    60 - :meth:`BuckyBall <GraphGenerators.BuckyBall>`
    61 - :meth:`BullGraph <GraphGenerators.BullGraph>`
    62 - :meth:`ButterflyGraph <GraphGenerators.ButterflyGraph>`
    63 - :meth:`CircularLadderGraph <GraphGenerators.CircularLadderGraph>`
    64 - :meth:`ClawGraph <GraphGenerators.ClawGraph>`
    65 - :meth:`CycleGraph <GraphGenerators.CycleGraph>`
    66 - :meth:`DiamondGraph <GraphGenerators.DiamondGraph>`
    67 - :meth:`EmptyGraph <GraphGenerators.EmptyGraph>`
    68 - :meth:`Grid2dGraph <GraphGenerators.Grid2dGraph>`
    69 - :meth:`GridGraph <GraphGenerators.GridGraph>`
    70 - :meth:`HouseGraph <GraphGenerators.HouseGraph>`
    71 - :meth:`HouseXGraph <GraphGenerators.HouseXGraph>`
    72 - :meth:`KrackhardtKiteGraph <GraphGenerators.KrackhardtKiteGraph>`
    73 - :meth:`LadderGraph <GraphGenerators.LadderGraph>`
    74 - :meth:`LollipopGraph <GraphGenerators.LollipopGraph>`
    75 - :meth:`PathGraph <GraphGenerators.PathGraph>`
    76 - :meth:`StarGraph <GraphGenerators.StarGraph>`
    77 - :meth:`ToroidalGrid2dGraph <GraphGenerators.ToroidalGrid2dGraph>`
    78 - :meth:`Toroidal6RegularGrid2dGraph <GraphGenerators.Toroidal6RegularGrid2dGraph>`
    79 - :meth:`WheelGraph <GraphGenerators.WheelGraph>`
     134__doc__ += """
     135**Families of graphs**
     136"""
    80137
    81 Platonic solids
    82 ---------------
     138__append_to_doc(
     139    ["BalancedTree",
     140     "BubbleSortGraph",
     141     "CirculantGraph",
     142     "CompleteBipartiteGraph",
     143     "CompleteGraph",
     144     "CubeGraph",
     145     "FibonacciTree",
     146     "FriendshipGraph",
     147     "FuzzyBallGraph",
     148     "GeneralizedPetersenGraph",
     149     "HanoiTowerGraph",
     150     "HyperStarGraph",
     151     "IntervalGraph",
     152     "KneserGraph",
     153     "LCFGraph",
     154     "MycielskiGraph",
     155     "MycielskiStep",
     156     "NKStarGraph",
     157     "NStarGraph",
     158     "OddGraph",
     159     "PaleyGraph",
     160     "RingedTree",
     161     "line_graph_forbidden_subgraphs",
     162     "PermutationGraph",
     163     "trees"])
    83164
    84 - :meth:`DodecahedralGraph <GraphGenerators.DodecahedralGraph>`
    85 - :meth:`HexahedralGraph <GraphGenerators.HexahedralGraph>`
    86 - :meth:`IcosahedralGraph <GraphGenerators.IcosahedralGraph>`
    87 - :meth:`OctahedralGraph <GraphGenerators.OctahedralGraph>`
    88 - :meth:`TetrahedralGraph <GraphGenerators.TetrahedralGraph>`
     165__doc__ += """
     166**Chessboard graphs**
     167"""
    89168
    90 Named Graphs
    91 ------------
     169__append_to_doc(
     170    ["BishopGraph",
     171     "KingGraph",
     172     "KnightGraph",
     173     "QueenGraph",
     174     "RookGraph"])
    92175
    93 - :meth:`Balaban10Cage <GraphGenerators.Balaban10Cage>`
    94 - :meth:`Balaban11Cage <GraphGenerators.Balaban11Cage>`
    95 - :meth:`BidiakisCube <GraphGenerators.BidiakisCube>`
    96 - :meth:`BiggsSmithGraph <GraphGenerators.BiggsSmithGraph>`
    97 - :meth:`BrinkmannGraph <GraphGenerators.BrinkmannGraph>`
    98 - :meth:`ChvatalGraph <GraphGenerators.ChvatalGraph>`
    99 - :meth:`ClebschGraph <GraphGenerators.ClebschGraph>`
    100 - :meth:`CoxeterGraph <GraphGenerators.CoxeterGraph>`
    101 - :meth:`DoubleStarSnark <GraphGenerators.DoubleStarSnark>`
    102 - :meth:`DesarguesGraph <GraphGenerators.DesarguesGraph>`
    103 - :meth:`DurerGraph <GraphGenerators.DurerGraph>`
    104 - :meth:`DyckGraph <GraphGenerators.DyckGraph>`
    105 - :meth:`EllinghamHorton54Graph <GraphGenerators.EllinghamHorton54Graph>`
    106 - :meth:`EllinghamHorton78Graph <GraphGenerators.EllinghamHorton78Graph>`
    107 - :meth:`ErreraGraph <GraphGenerators.ErreraGraph>`
    108 - :meth:`FlowerSnark <GraphGenerators.FlowerSnark>`
    109 - :meth:`FosterGraph <GraphGenerators.FosterGraph>`
    110 - :meth:`FranklinGraph <GraphGenerators.FranklinGraph>`
    111 - :meth:`FruchtGraph <GraphGenerators.FruchtGraph>`
    112 - :meth:`GoldnerHararyGraph <GraphGenerators.GoldnerHararyGraph>`
    113 - :meth:`GrayGraph <GraphGenerators.GrayGraph>`
    114 - :meth:`GrotzschGraph <GraphGenerators.GrotzschGraph>`
    115 - :meth:`HallJankoGraph <GraphGenerators.HallJankoGraph>`
    116 - :meth:`HararyGraph <GraphGenerators.HararyGraph>`
    117 - :meth:`HarriesGraph <GraphGenerators.HarriesGraph>`
    118 - :meth:`HarriesWongGraph <GraphGenerators.HarriesWongGraph>`
    119 - :meth:`HeawoodGraph <GraphGenerators.HeawoodGraph>`
    120 - :meth:`HerschelGraph <GraphGenerators.HerschelGraph>`
    121 - :meth:`HigmanSimsGraph <GraphGenerators.HigmanSimsGraph>`
    122 - :meth:`HoffmanSingletonGraph <GraphGenerators.HoffmanSingletonGraph>`
    123 - :meth:`HoffmanGraph <GraphGenerators.HoffmanGraph>`
    124 - :meth:`HoltGraph <GraphGenerators.HoltGraph>`
    125 - :meth:`LjubljanaGraph <GraphGenerators.LjubljanaGraph>`
    126 - :meth:`McGeeGraph <GraphGenerators.McGeeGraph>`
    127 - :meth:`MoebiusKantorGraph <GraphGenerators.MoebiusKantorGraph>`
    128 - :meth:`MoserSpindle <GraphGenerators.MoserSpindle>`
    129 - :meth:`NauruGraph <GraphGenerators.NauruGraph>`
    130 - :meth:`PappusGraph <GraphGenerators.PappusGraph>`
    131 - :meth:`PetersenGraph <GraphGenerators.PetersenGraph>`
    132 - :meth:`ShrikhandeGraph <GraphGenerators.ShrikhandeGraph>`
    133 - :meth:`ThomsenGraph <GraphGenerators.ThomsenGraph>`
    134 - :meth:`Tutte12Cage <GraphGenerators.Tutte12Cage>`
    135 - :meth:`TutteCoxeterGraph <GraphGenerators.TutteCoxeterGraph>`
    136 - :meth:`WagnerGraph <GraphGenerators.WagnerGraph>`
     176__doc__ += """
     177**Pseudofractal graphs**
     178"""
    137179
     180__append_to_doc(["DorogovtsevGoltsevMendesGraph"])
    138181
    139 Families of graphs
    140 ------------------
     182__doc__ += """
     183**Random graphs**
     184"""
    141185
    142 - :meth:`BalancedTree <GraphGenerators.BalancedTree>`
    143 - :meth:`BubbleSortGraph <GraphGenerators.BubbleSortGraph>`
    144 - :meth:`CirculantGraph <GraphGenerators.CirculantGraph>`
    145 - :meth:`CompleteBipartiteGraph <GraphGenerators.CompleteBipartiteGraph>`
    146 - :meth:`CompleteGraph <GraphGenerators.CompleteGraph>`
    147 - :meth:`CubeGraph <GraphGenerators.CubeGraph>`
    148 - :meth:`FibonacciTree <GraphGenerators.FibonacciTree>`
    149 - :meth:`FriendshipGraph <GraphGenerators.FriendshipGraph>`
    150 - :meth:`FuzzyBallGraph <GraphGenerators.FuzzyBallGraph>`
    151 - :meth:`GeneralizedPetersenGraph <GraphGenerators.GeneralizedPetersenGraph>`
    152 - :meth:`HanoiTowerGraph <GraphGenerators.HanoiTowerGraph>`
    153 - :meth:`HyperStarGraph <GraphGenerators.HyperStarGraph>`
    154 - :meth:`IntervalGraph <GraphGenerators.IntervalGraph>`
    155 - :meth:`KneserGraph <GraphGenerators.KneserGraph>`
    156 - :meth:`LCFGraph <GraphGenerators.LCFGraph>`
    157 - :meth:`MycielskiGraph <GraphGenerators.MycielskiGraph>`
    158 - :meth:`MycielskiStep <GraphGenerators.MycielskiStep>`
    159 - :meth:`NKStarGraph <GraphGenerators.NKStarGraph>`
    160 - :meth:`NStarGraph <GraphGenerators.NStarGraph>`
    161 - :meth:`OddGraph <GraphGenerators.OddGraph>`
    162 - :meth:`PaleyGraph <GraphGenerators.PaleyGraph>`
    163 - :meth:`RingedTree <GraphGenerators.RingedTree>`
    164 - :meth:`line_graph_forbidden_subgraphs <GraphGenerators.line_graph_forbidden_subgraphs>`
    165 - :meth:`PermutationGraph <GraphGenerators.PermutationGraph>`
    166 - :meth:`trees <GraphGenerators.trees>`
     186__append_to_doc(
     187    ["RandomBarabasiAlbert",
     188     "RandomBipartite",
     189     "RandomGNM",
     190     "RandomGNP",
     191     "RandomHolmeKim",
     192     "RandomInterval",
     193     "RandomLobster",
     194     "RandomNewmanWattsStrogatz",
     195     "RandomRegular",
     196     "RandomShell",
     197     "RandomTree",
     198     "RandomTreePowerlaw"])
    167199
    168 Chessboard graphs :
     200__doc__ += """
     201**Graphs with a given degree sequence**
     202"""
    169203
    170 - :meth:`BishopGraph <GraphGenerators.BishopGraph>`
    171 - :meth:`KingGraph <GraphGenerators.KingGraph>`
    172 - :meth:`KnightGraph <GraphGenerators.KnightGraph>`
    173 - :meth:`QueenGraph <GraphGenerators.QueenGraph>`
    174 - :meth:`RookGraph <GraphGenerators.RookGraph>`
     204__append_to_doc(
     205    ["DegreeSequence",
     206     "DegreeSequenceBipartite",
     207     "DegreeSequenceConfigurationModel",
     208     "DegreeSequenceExpected",
     209     "DegreeSequenceTree"])
    175210
    176 Pseudofractal graphs
    177 --------------------
     211__doc__ += """
     212**Miscellaneous**
     213"""
    178214
    179 - :meth:`DorogovtsevGoltsevMendesGraph <GraphGenerators.DorogovtsevGoltsevMendesGraph>`
     215__append_to_doc(
     216    ["WorldMap"]
     217    )
    180218
    181 Random graphs
    182 -------------
    183 
    184 - :meth:`RandomBarabasiAlbert <GraphGenerators.RandomBarabasiAlbert>`
    185 - :meth:`RandomBipartite <GraphGenerators.RandomBipartite>`
    186 - :meth:`RandomGNM <GraphGenerators.RandomGNM>`
    187 - :meth:`RandomGNP <GraphGenerators.RandomGNP>`
    188 - :meth:`RandomHolmeKim <GraphGenerators.RandomHolmeKim>`
    189 - :meth:`RandomInterval <GraphGenerators.RandomInterval>`
    190 - :meth:`RandomLobster <GraphGenerators.RandomLobster>`
    191 - :meth:`RandomNewmanWattsStrogatz <GraphGenerators.RandomNewmanWattsStrogatz>`
    192 - :meth:`RandomRegular <GraphGenerators.RandomRegular>`
    193 - :meth:`RandomShell <GraphGenerators.RandomShell>`
    194 - :meth:`RandomTree <GraphGenerators.RandomTree>`
    195 - :meth:`RandomTreePowerlaw <GraphGenerators.RandomTreePowerlaw>`
    196 
    197 
    198 Graphs with a given degree sequence
    199 -----------------------------------
    200 
    201 - :meth:`DegreeSequence <GraphGenerators.DegreeSequence>`
    202 - :meth:`DegreeSequenceBipartite <GraphGenerators.DegreeSequenceBipartite>`
    203 - :meth:`DegreeSequenceConfigurationModel <GraphGenerators.DegreeSequenceConfigurationModel>`
    204 - :meth:`DegreeSequenceExpected <GraphGenerators.DegreeSequenceExpected>`
    205 - :meth:`DegreeSequenceTree <GraphGenerators.DegreeSequenceTree>`
    206 
    207 
    208 Miscellaneous
    209 -------------
    210 
    211 - :meth:`WorldMap <GraphGenerators.WorldMap>`
    212 
     219__doc__ += """
    213220
    214221AUTHORS:
    215222
     
    246253
    247254- Edward Scheinerman (2010-08-11): RandomTree
    248255
    249 - Ed Scheinerman (2010-08-21): added Grotzsch graph and Mycielski graphs 
     256- Ed Scheinerman (2010-08-21): added Grotzsch graph and Mycielski graphs
    250257
    251258- Minh Van Nguyen (2010-11-26): added more named graphs
    252259
     
    256263
    257264- David Coudert (2012-08-02): added chessboard graphs: Queen, King,
    258265  Knight, Bishop, and Rook graphs
     266
     267Functions and methods
     268---------------------
    259269"""
    260270
    261271###########################################################################
     
    277287
    278288class GraphGenerators():
    279289    r"""
    280     A class consisting of constructors for several common graphs, as
    281     well as orderly generation of isomorphism class representatives. See the
    282     section :ref:`organization` for a list of supported constructors.
     290    A class consisting of constructors for several common graphs, as well as
     291    orderly generation of isomorphism class representatives. See the
     292    :mod:`module's help <sage.graphs.graph_generators>` for a list of supported
     293    constructors.
    283294
    284295    A list of all graphs and graph structures (other than isomorphism class
    285296    representatives) in this database is available via tab completion. Type
  • sage/graphs/graph_plot.py

    diff --git a/sage/graphs/graph_plot.py b/sage/graphs/graph_plot.py
    a b  
    11"""
    22Graph Plotting
     3
     4All graphs have an associated Sage graphics object, which you can display::
     5
     6    sage: G = graphs.WheelGraph(15)
     7    sage: P = G.plot()
     8    sage: P.show() # long time
     9
     10If you create a graph in Sage using the ``Graph`` command, then plot that graph,
     11the positioning of nodes is determined using the spring-layout algorithm. For
     12the special graph constructors, which you get using ``graphs.[tab]``, the
     13positions are preset. For example, consider the Petersen graph with default node
     14positioning vs. the Petersen graph constructed by this database::
     15
     16    sage: petersen_spring = Graph({0:[1,4,5], 1:[0,2,6], 2:[1,3,7], 3:[2,4,8], 4:[0,3,9], 5:[0,7,8], 6:[1,8,9], 7:[2,5,9], 8:[3,5,6], 9:[4,6,7]})
     17    sage: petersen_spring.show() # long time
     18    sage: petersen_database = graphs.PetersenGraph()
     19    sage: petersen_database.show() # long time
     20
     21For all the constructors in this database (except the octahedral, dodecahedral,
     22random and empty graphs), the position dictionary is filled in, instead of using
     23the spring-layout algorithm.
     24
     25Functions and methods
     26---------------------
    327"""
    428
    529#*****************************************************************************
    630#      Copyright (C) 2009   Emily Kirkman
    731#                    2009   Robert L. Miller <rlmillster@gmail.com>
    8 #                   
     32#
    933#  Distributed under the terms of the GNU General Public License (GPL)
    1034#
    1135#    This code is distributed in the hope that it will be useful,