Commit 00de67ff authored by Tiago Peixoto's avatar Tiago Peixoto

Sphinx cleanup and docs update

parent 4f0c7fe6
......@@ -34,19 +34,10 @@ nobase_dist_graphtooldoc_DATA = \
doc/demos/index.rst \
doc/demos/animation/animation.rst \
doc/demos/inference/inference.rst \
doc/sphinxext/README.txt \
doc/sphinxext/LICENSE.txt \
doc/sphinxext/__init__.py \
doc/sphinxext/setup.py \
doc/sphinxext/comment_eater.py \
doc/sphinxext/docscrape.py \
doc/sphinxext/MANIFEST.in \
doc/sphinxext/phantom_import.py \
doc/sphinxext/compiler_unparse.py \
doc/sphinxext/docscrape_sphinx.py \
doc/sphinxext/numpydoc.py \
doc/sphinxext/traitsdoc.py \
doc/sphinxext/tests/test_docscrape.py \
doc/gt_theme/static/flasky.css \
doc/gt_theme/static/gt_style.css \
doc/gt_theme/theme.conf \
......
......@@ -184,7 +184,7 @@ intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
extlinks_fancy = {'ticket': (['https://graph-tool.skewed.de/tickets/ticket/{0}'],
['ticket {0}']),
'doi': (['https://dx.doi.org/{0}',
'https://sci-hub.cc/{0}',
'https://sci-hub.tw/{0}',
'https://scihub22266oqcxt.onion.link/{0}'],
['DOI: {0}', "sci-hub", "@tor"]),
'arxiv': (['https://arxiv.org/abs/{0}'], ['arXiv: {0}'])}
......
......@@ -359,7 +359,7 @@ illustrate its use with the neural network of the `C. elegans
.. testsetup:: celegans
gt.seed_rng(43)
gt.seed_rng(47)
.. testcode:: celegans
......@@ -411,10 +411,10 @@ which shows the number of nodes and groups in all levels:
.. testoutput:: celegans
l: 0, N: 297, B: 15
l: 1, N: 15, B: 6
l: 2, N: 6, B: 4
l: 3, N: 4, B: 1
l: 0, N: 297, B: 17
l: 1, N: 17, B: 9
l: 2, N: 9, B: 3
l: 3, N: 3, B: 1
The hierarchical levels themselves are represented by individual
:meth:`~graph_tool.inference.BlockState` instances obtained via the
......@@ -428,10 +428,10 @@ The hierarchical levels themselves are represented by individual
.. testoutput:: celegans
<BlockState object with 15 blocks (15 nonempty), degree-corrected, for graph <Graph object, directed, with 297 vertices and 2359 edges at 0x...>, at 0x...>
<BlockState object with 6 blocks (6 nonempty), for graph <Graph object, directed, with 15 vertices and 133 edges at 0x...>, at 0x...>
<BlockState object with 4 blocks (4 nonempty), for graph <Graph object, directed, with 6 vertices and 33 edges at 0x...>, at 0x...>
<BlockState object with 1 blocks (1 nonempty), for graph <Graph object, directed, with 4 vertices and 16 edges at 0x...>, at 0x...>
<BlockState object with 17 blocks (17 nonempty), degree-corrected, for graph <Graph object, directed, with 297 vertices and 2359 edges at 0x...>, at 0x...>
<BlockState object with 9 blocks (9 nonempty), for graph <Graph object, directed, with 17 vertices and 156 edges at 0x...>, at 0x...>
<BlockState object with 3 blocks (3 nonempty), for graph <Graph object, directed, with 9 vertices and 57 edges at 0x...>, at 0x...>
<BlockState object with 1 blocks (1 nonempty), for graph <Graph object, directed, with 3 vertices and 9 edges at 0x...>, at 0x...>
This means that we can inspect the hierarchical partition just as before:
......@@ -446,7 +446,7 @@ This means that we can inspect the hierarchical partition just as before:
.. testoutput:: celegans
5
7
0
0
......@@ -476,8 +476,8 @@ case of the `C. elegans` network we have
.. testoutput:: model-selection
:options: +NORMALIZE_WHITESPACE
Non-degree-corrected DL: 8478.791367...
Degree-corrected DL: 8207.895440...
Non-degree-corrected DL: 8456.994339...
Degree-corrected DL: 8233.850036...
Since it yields the smallest description length, the degree-corrected
fit should be preferred. The statistical significance of the choice can
......@@ -503,12 +503,12 @@ fits. In our particular case, we have
.. testoutput:: model-selection
:options: +NORMALIZE_WHITESPACE
ln Λ: -270.895926...
ln Λ: -223.144303...
The precise threshold that should be used to decide when to `reject a
hypothesis <https://en.wikipedia.org/wiki/Hypothesis_testing>`_ is
subjective and context-dependent, but the value above implies that the
particular degree-corrected fit is around :math:`\mathrm{e}^{270} \approx 10^{117}`
particular degree-corrected fit is around :math:`\mathrm{e}^{233} \approx 10^{96}`
times more likely than the non-degree corrected one, and hence it can be
safely concluded that it provides a substantially better fit.
......@@ -530,12 +530,12 @@ example, for the American football network above, we have:
.. testoutput:: model-selection
:options: +NORMALIZE_WHITESPACE
Non-degree-corrected DL: 1747.500987...
Degree-corrected DL: 1780.576716...
ln Λ: -33.075729...
Non-degree-corrected DL: 1734.814739...
Degree-corrected DL: 1780.576716...
ln Λ: -45.761977...
Hence, with a posterior odds ratio of :math:`\Lambda \approx \mathrm{e}^{-33} \approx
10^{-14}` in favor of the non-degree-corrected model, it seems like the
Hence, with a posterior odds ratio of :math:`\Lambda \approx \mathrm{e}^{-45} \approx
10^{-19}` in favor of the non-degree-corrected model, it seems like the
degree-corrected variant is an unnecessarily complex description for
this network.
......@@ -595,8 +595,8 @@ random partition into 20 groups
.. testoutput:: model-averaging
Change in description length: -358.602505...
Number of accepted vertex moves: 36528
Change in description length: -365.317522...
Number of accepted vertex moves: 38213
.. note::
......@@ -619,8 +619,8 @@ random partition into 20 groups
.. testoutput:: model-averaging
Change in description length: 16.127057...
Number of accepted vertex moves: 39217
Change in description length: 1.660677...
Number of accepted vertex moves: 40461
Although the above is sufficient to implement model averaging, there is a
convenience function called
......@@ -641,34 +641,51 @@ will output:
.. testoutput:: model-averaging
:options: +NORMALIZE_WHITESPACE
niter: 1 count: 0 breaks: 0 min_S: 706.94151 max_S: 715.47667 S: 706.94151 ΔS: -8.53516 moves: 394
niter: 2 count: 0 breaks: 0 min_S: 706.94151 max_S: 729.78585 S: 729.78585 ΔS: 22.8443 moves: 420
niter: 3 count: 1 breaks: 0 min_S: 706.94151 max_S: 729.78585 S: 720.88036 ΔS: -8.90549 moves: 406
niter: 4 count: 2 breaks: 0 min_S: 706.94151 max_S: 729.78585 S: 726.95968 ΔS: 6.07932 moves: 370
niter: 5 count: 3 breaks: 0 min_S: 706.94151 max_S: 729.78585 S: 721.59919 ΔS: -5.36049 moves: 384
niter: 6 count: 4 breaks: 0 min_S: 706.94151 max_S: 729.78585 S: 724.02327 ΔS: 2.42408 moves: 379
niter: 7 count: 5 breaks: 0 min_S: 706.94151 max_S: 729.78585 S: 715.51448 ΔS: -8.50879 moves: 352
niter: 8 count: 6 breaks: 0 min_S: 706.94151 max_S: 729.78585 S: 711.38261 ΔS: -4.13187 moves: 365
niter: 9 count: 7 breaks: 0 min_S: 706.94151 max_S: 729.78585 S: 717.02574 ΔS: 5.64312 moves: 364
niter: 10 count: 8 breaks: 0 min_S: 706.94151 max_S: 729.78585 S: 714.98290 ΔS: -2.04284 moves: 358
niter: 11 count: 9 breaks: 0 min_S: 706.94151 max_S: 729.78585 S: 721.79965 ΔS: 6.81675 moves: 382
niter: 12 count: 0 breaks: 1 min_S: 709.20806 max_S: 709.20806 S: 709.20806 ΔS: -12.5916 moves: 345
niter: 13 count: 0 breaks: 1 min_S: 704.69711 max_S: 709.20806 S: 704.69711 ΔS: -4.51094 moves: 361
niter: 14 count: 0 breaks: 1 min_S: 704.09567 max_S: 709.20806 S: 704.09567 ΔS: -0.601444 moves: 373
niter: 15 count: 1 breaks: 1 min_S: 704.09567 max_S: 709.20806 S: 704.71189 ΔS: 0.616215 moves: 393
niter: 16 count: 0 breaks: 1 min_S: 704.09567 max_S: 717.16180 S: 717.16180 ΔS: 12.4499 moves: 379
niter: 17 count: 1 breaks: 1 min_S: 704.09567 max_S: 717.16180 S: 708.38966 ΔS: -8.77214 moves: 428
niter: 18 count: 0 breaks: 1 min_S: 704.09567 max_S: 721.85296 S: 721.85296 ΔS: 13.4633 moves: 410
niter: 19 count: 1 breaks: 1 min_S: 704.09567 max_S: 721.85296 S: 720.27396 ΔS: -1.57901 moves: 385
niter: 20 count: 2 breaks: 1 min_S: 704.09567 max_S: 721.85296 S: 706.59958 ΔS: -13.6744 moves: 410
niter: 21 count: 3 breaks: 1 min_S: 704.09567 max_S: 721.85296 S: 711.00676 ΔS: 4.40718 moves: 404
niter: 22 count: 4 breaks: 1 min_S: 704.09567 max_S: 721.85296 S: 717.22981 ΔS: 6.22305 moves: 403
niter: 23 count: 5 breaks: 1 min_S: 704.09567 max_S: 721.85296 S: 714.83148 ΔS: -2.39833 moves: 414
niter: 24 count: 6 breaks: 1 min_S: 704.09567 max_S: 721.85296 S: 710.06471 ΔS: -4.76676 moves: 400
niter: 25 count: 7 breaks: 1 min_S: 704.09567 max_S: 721.85296 S: 706.67930 ΔS: -3.38541 moves: 377
niter: 26 count: 8 breaks: 1 min_S: 704.09567 max_S: 721.85296 S: 704.53434 ΔS: -2.14496 moves: 399
niter: 27 count: 9 breaks: 1 min_S: 704.09567 max_S: 721.85296 S: 720.67029 ΔS: 16.1360 moves: 397
niter: 28 count: 10 breaks: 2 min_S: 704.09567 max_S: 721.85296 S: 705.87845 ΔS: -14.7918 moves: 388
niter: 1 count: 0 breaks: 0 min_S: 706.26857 max_S: 708.14483 S: 708.14483 ΔS: 1.87626 moves: 418
niter: 2 count: 0 breaks: 0 min_S: 699.23453 max_S: 708.14483 S: 699.23453 ΔS: -8.91030 moves: 409
niter: 3 count: 0 breaks: 0 min_S: 699.23453 max_S: 715.33531 S: 715.33531 ΔS: 16.1008 moves: 414
niter: 4 count: 0 breaks: 0 min_S: 699.23453 max_S: 723.13301 S: 723.13301 ΔS: 7.79770 moves: 391
niter: 5 count: 1 breaks: 0 min_S: 699.23453 max_S: 723.13301 S: 702.93354 ΔS: -20.1995 moves: 411
niter: 6 count: 2 breaks: 0 min_S: 699.23453 max_S: 723.13301 S: 706.39029 ΔS: 3.45675 moves: 389
niter: 7 count: 3 breaks: 0 min_S: 699.23453 max_S: 723.13301 S: 706.80859 ΔS: 0.418293 moves: 404
niter: 8 count: 4 breaks: 0 min_S: 699.23453 max_S: 723.13301 S: 707.61960 ΔS: 0.811010 moves: 417
niter: 9 count: 5 breaks: 0 min_S: 699.23453 max_S: 723.13301 S: 706.46577 ΔS: -1.15383 moves: 392
niter: 10 count: 6 breaks: 0 min_S: 699.23453 max_S: 723.13301 S: 714.34671 ΔS: 7.88094 moves: 410
niter: 11 count: 7 breaks: 0 min_S: 699.23453 max_S: 723.13301 S: 706.43194 ΔS: -7.91477 moves: 383
niter: 12 count: 8 breaks: 0 min_S: 699.23453 max_S: 723.13301 S: 705.19434 ΔS: -1.23760 moves: 405
niter: 13 count: 9 breaks: 0 min_S: 699.23453 max_S: 723.13301 S: 702.21395 ΔS: -2.98039 moves: 423
niter: 14 count: 0 breaks: 1 min_S: 715.54878 max_S: 715.54878 S: 715.54878 ΔS: 13.3348 moves: 400
niter: 15 count: 0 breaks: 1 min_S: 715.54878 max_S: 716.65842 S: 716.65842 ΔS: 1.10964 moves: 413
niter: 16 count: 0 breaks: 1 min_S: 701.19994 max_S: 716.65842 S: 701.19994 ΔS: -15.4585 moves: 382
niter: 17 count: 1 breaks: 1 min_S: 701.19994 max_S: 716.65842 S: 715.56997 ΔS: 14.3700 moves: 394
niter: 18 count: 0 breaks: 1 min_S: 701.19994 max_S: 719.25577 S: 719.25577 ΔS: 3.68580 moves: 404
niter: 19 count: 0 breaks: 1 min_S: 701.19994 max_S: 723.78811 S: 723.78811 ΔS: 4.53233 moves: 413
niter: 20 count: 1 breaks: 1 min_S: 701.19994 max_S: 723.78811 S: 709.77340 ΔS: -14.0147 moves: 387
niter: 21 count: 2 breaks: 1 min_S: 701.19994 max_S: 723.78811 S: 714.14891 ΔS: 4.37551 moves: 419
niter: 22 count: 3 breaks: 1 min_S: 701.19994 max_S: 723.78811 S: 722.05875 ΔS: 7.90984 moves: 399
niter: 23 count: 4 breaks: 1 min_S: 701.19994 max_S: 723.78811 S: 714.32503 ΔS: -7.73371 moves: 422
niter: 24 count: 5 breaks: 1 min_S: 701.19994 max_S: 723.78811 S: 708.53927 ΔS: -5.78576 moves: 392
niter: 25 count: 6 breaks: 1 min_S: 701.19994 max_S: 723.78811 S: 714.05889 ΔS: 5.51962 moves: 404
niter: 26 count: 7 breaks: 1 min_S: 701.19994 max_S: 723.78811 S: 713.93196 ΔS: -0.126937 moves: 414
niter: 27 count: 8 breaks: 1 min_S: 701.19994 max_S: 723.78811 S: 709.49863 ΔS: -4.43333 moves: 410
niter: 28 count: 9 breaks: 1 min_S: 701.19994 max_S: 723.78811 S: 707.42167 ΔS: -2.07696 moves: 397
niter: 29 count: 0 breaks: 1 min_S: 699.89982 max_S: 723.78811 S: 699.89982 ΔS: -7.52185 moves: 388
niter: 30 count: 0 breaks: 1 min_S: 698.57305 max_S: 723.78811 S: 698.57305 ΔS: -1.32677 moves: 391
niter: 31 count: 1 breaks: 1 min_S: 698.57305 max_S: 723.78811 S: 706.02629 ΔS: 7.45324 moves: 412
niter: 32 count: 2 breaks: 1 min_S: 698.57305 max_S: 723.78811 S: 701.97778 ΔS: -4.04852 moves: 421
niter: 33 count: 3 breaks: 1 min_S: 698.57305 max_S: 723.78811 S: 707.50134 ΔS: 5.52356 moves: 410
niter: 34 count: 4 breaks: 1 min_S: 698.57305 max_S: 723.78811 S: 708.56686 ΔS: 1.06552 moves: 424
niter: 35 count: 0 breaks: 1 min_S: 698.57305 max_S: 724.07361 S: 724.07361 ΔS: 15.5067 moves: 399
niter: 36 count: 1 breaks: 1 min_S: 698.57305 max_S: 724.07361 S: 723.51969 ΔS: -0.553915 moves: 384
niter: 37 count: 2 breaks: 1 min_S: 698.57305 max_S: 724.07361 S: 702.36708 ΔS: -21.1526 moves: 406
niter: 38 count: 3 breaks: 1 min_S: 698.57305 max_S: 724.07361 S: 707.60129 ΔS: 5.23420 moves: 405
niter: 39 count: 4 breaks: 1 min_S: 698.57305 max_S: 724.07361 S: 709.67542 ΔS: 2.07413 moves: 400
niter: 40 count: 5 breaks: 1 min_S: 698.57305 max_S: 724.07361 S: 714.52753 ΔS: 4.85212 moves: 398
niter: 41 count: 6 breaks: 1 min_S: 698.57305 max_S: 724.07361 S: 707.86563 ΔS: -6.66190 moves: 409
niter: 42 count: 7 breaks: 1 min_S: 698.57305 max_S: 724.07361 S: 718.80926 ΔS: 10.9436 moves: 400
niter: 43 count: 8 breaks: 1 min_S: 698.57305 max_S: 724.07361 S: 716.37312 ΔS: -2.43615 moves: 378
niter: 44 count: 9 breaks: 1 min_S: 698.57305 max_S: 724.07361 S: 713.76944 ΔS: -2.60368 moves: 399
niter: 45 count: 10 breaks: 2 min_S: 698.57305 max_S: 724.07361 S: 715.29009 ΔS: 1.52066 moves: 421
Note that the value of ``wait`` above was made purposefully low so that
the output would not be overly long. The most appropriate value requires
......@@ -799,8 +816,8 @@ network as above.
.. testoutput:: nested-model-averaging
Change in description length: 10.744544...
Number of accepted vertex moves: 50702
Change in description length: 2.371018...
Number of accepted vertex moves: 56087
Similarly to the the non-nested case, we can use
:func:`~graph_tool.inference.mcmc_equilibrate` to do most of the boring
......@@ -1065,8 +1082,8 @@ evidence efficiently, as we show below, using
.. testoutput:: model-evidence
Model evidence for deg_corr = True: -559.5804... (mean field), -841.8073... (Bethe)
Model evidence for deg_corr = False: -581.9044... (mean field), -712.7732... (Bethe)
Model evidence for deg_corr = True: -569.590426... (mean field), -817.788531... (Bethe)
Model evidence for deg_corr = False: -587.028530... (mean field), -736.990655... (Bethe)
If we consider the more accurate approximation, the outcome shows a
preference for the non-degree-corrected model.
......@@ -1130,8 +1147,8 @@ approach for the same network, using the nested model.
.. testoutput:: model-evidence
Model evidence for deg_corr = True: -553.6993... (mean field), -724.2353... (Bethe)
Model evidence for deg_corr = False: -530.0536... (mean field), -637.6968... (Bethe)
Model evidence for deg_corr = True: -551.228195... (mean field), -740.460493... (Bethe)
Model evidence for deg_corr = False: -544.660366... (mean field), -649.135026... (Bethe)
The results are similar: If we consider the most accurate approximation,
the non-degree-corrected model possesses the largest evidence. Note also
......@@ -1386,9 +1403,9 @@ Therefore, we can compute the posterior odds ratio between both models as:
.. testoutput:: food-web
:options: +NORMALIZE_WHITESPACE
ln Λ: -6.560861...
ln Λ: -70.145685...
A value of :math:`\Lambda \approx \mathrm{e}^{-43} \approx 10^{-19}` in
A value of :math:`\Lambda \approx \mathrm{e}^{-70} \approx 10^{-30}` in
favor the exponential model indicates that the log-normal model does not
provide a better fit for this particular data. Based on this, we
conclude that the exponential model should be preferred in this case.
......
-------------------------------------------------------------------------------
The files
- numpydoc.py
- docscrape.py
- docscrape_sphinx.py
- phantom_import.py
have the following license:
Copyright (C) 2008 Stefan van der Walt <stefan@mentat.za.net>, Pauli Virtanen <pav@iki.fi>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
-------------------------------------------------------------------------------
The files
- compiler_unparse.py
- comment_eater.py
- traitsdoc.py
have the following license:
This software is OSI Certified Open Source Software.
OSI Certified is a certification mark of the Open Source Initiative.
Copyright (c) 2006, Enthought, Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of Enthought, Inc. nor the names of its contributors may
be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-------------------------------------------------------------------------------
The file
- plot_directive.py
originates from Matplotlib (http://matplotlib.sf.net/) which has
the following license:
Copyright (c) 2002-2008 John D. Hunter; All Rights Reserved.
1. This LICENSE AGREEMENT is between John D. Hunter (“JDH”), and the Individual or Organization (“Licensee”) accessing and otherwise using matplotlib software in source or binary form and its associated documentation.
2. Subject to the terms and conditions of this License Agreement, JDH hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use matplotlib 0.98.3 alone or in any derivative version, provided, however, that JDH’s License Agreement and JDH’s notice of copyright, i.e., “Copyright (c) 2002-2008 John D. Hunter; All Rights Reserved” are retained in matplotlib 0.98.3 alone or in any derivative version prepared by Licensee.
3. In the event Licensee prepares a derivative work that is based on or incorporates matplotlib 0.98.3 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to matplotlib 0.98.3.
4. JDH is making matplotlib 0.98.3 available to Licensee on an “AS IS” basis. JDH MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, JDH MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF MATPLOTLIB 0.98.3 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
5. JDH SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF MATPLOTLIB 0.98.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING MATPLOTLIB 0.98.3, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.
7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between JDH and Licensee. This License Agreement does not grant permission to use JDH trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party.
8. By copying, installing or otherwise using matplotlib 0.98.3, Licensee agrees to be bound by the terms and conditions of this License Agreement.
recursive-include tests *.py
include *.txt
=====================================
numpydoc -- Numpy's Sphinx extensions
=====================================
Numpy's documentation uses several custom extensions to Sphinx. These
are shipped in this ``numpydoc`` package, in case you want to make use
of them in third-party projects.
The following extensions are available:
- ``numpydoc``: support for the Numpy docstring format in Sphinx, and add
the code description directives ``np:function``, ``np-c:function``, etc.
that support the Numpy docstring syntax.
- ``numpydoc.traitsdoc``: For gathering documentation about Traits attributes.
- ``numpydoc.plot_directive``: Adaptation of Matplotlib's ``plot::``
directive. Note that this implementation may still undergo severe
changes or eventually be deprecated.
numpydoc
========
Numpydoc inserts a hook into Sphinx's autodoc that converts docstrings
following the Numpy/Scipy format to a form palatable to Sphinx.
Options
-------
The following options can be set in conf.py:
- numpydoc_use_plots: bool
Whether to produce ``plot::`` directives for Examples sections that
contain ``import matplotlib``.
- numpydoc_show_class_members: bool
Whether to show all members of a class in the Methods and Attributes
sections automatically.
- numpydoc_edit_link: bool (DEPRECATED -- edit your HTML template instead)
Whether to insert an edit link after docstrings.
from .numpydoc import setup
"""Extract reference documentation from the NumPy source tree.
"""
import inspect
import textwrap
import re
import pydoc
from io import StringIO
from warnings import warn
import collections
class Reader(object):
"""A line-based string reader.
"""
def __init__(self, data):
"""
Parameters
----------
data : str
String with lines separated by '\n'.
"""
if isinstance(data,list):
self._str = data
else:
self._str = data.split('\n') # store string as list of lines
self.reset()
def __getitem__(self, n):
return self._str[n]
def reset(self):
self._l = 0 # current line nr
def read(self):
if not self.eof():
out = self[self._l]
self._l += 1
return out
else:
return ''
def seek_next_non_empty_line(self):
for l in self[self._l:]:
if l.strip():
break
else:
self._l += 1
def eof(self):
return self._l >= len(self._str)
def read_to_condition(self, condition_func):
start = self._l
for line in self[start:]:
if condition_func(line):
return self[start:self._l]
self._l += 1
if self.eof():
return self[start:self._l+1]
return []
def read_to_next_empty_line(self):
self.seek_next_non_empty_line()
def is_empty(line):
return not line.strip()
return self.read_to_condition(is_empty)
def read_to_next_unindented_line(self):
def is_unindented(line):
return (line.strip() and (len(line.lstrip()) == len(line)))
return self.read_to_condition(is_unindented)
def peek(self,n=0):
if self._l + n < len(self._str):
return self[self._l + n]
else:
return ''
def is_empty(self):
return not ''.join(self._str).strip()
class NumpyDocString(object):
def __init__(self, docstring, config={}):
docstring = textwrap.dedent(docstring).split('\n')
self._doc = Reader(docstring)
self._parsed_data = {
'Signature': '',
'Summary': [''],
'Extended Summary': [],
'Parameters': [],
'Returns': [],
'Raises': [],
'Warns': [],
'Other Parameters': [],
'Attributes': [],
'Methods': [],
'See Also': [],
'Notes': [],
'Warnings': [],
'References': '',
'Examples': '',
'index': {}
}
self._parse()
def __getitem__(self,key):
return self._parsed_data[key]
def __setitem__(self,key,val):
if key not in self._parsed_data:
warn("Unknown section %s" % key)
else:
self._parsed_data[key] = val
def _is_at_section(self):
self._doc.seek_next_non_empty_line()
if self._doc.eof():
return False
l1 = self._doc.peek().strip() # e.g. Parameters
if l1.startswith('.. index::'):
return True
l2 = self._doc.peek(1).strip() # ---------- or ==========
return l2.startswith('-'*len(l1)) or l2.startswith('='*len(l1))
def _strip(self,doc):
i = 0
j = 0
for i,line in enumerate(doc):
if line.strip(): break
for j,line in enumerate(doc[::-1]):
if line.strip(): break
return doc[i:len(doc)-j]
def _read_to_next_section(self):
section = self._doc.read_to_next_empty_line()
while not self._is_at_section() and not self._doc.eof():
if not self._doc.peek(-1).strip(): # previous line was empty
section += ['']
section += self._doc.read_to_next_empty_line()
return section
def _read_sections(self):
while not self._doc.eof():
data = self._read_to_next_section()
name = data[0].strip()
if name.startswith('..'): # index section
yield name, data[1:]
elif len(data) < 2:
yield StopIteration
else:
yield name, self._strip(data[2:])
def _parse_param_list(self,content):
r = Reader(content)
params = []
while not r.eof():
header = r.read().strip()
if ' : ' in header:
arg_name, arg_type = header.split(' : ')[:2]
else:
arg_name, arg_type = header, ''
desc = r.read_to_next_unindented_line()
desc = dedent_lines(desc)
params.append((arg_name,arg_type,desc))
return params
_name_rgx = re.compile(r"^\s*(:(?P<role>\w+):`(?P<name>[a-zA-Z0-9_.-]+)`|"
r" (?P<name2>[a-zA-Z0-9_.-]+))\s*", re.X)
def _parse_see_also(self, content):
"""
func_name : Descriptive text
continued text
another_func_name : Descriptive text
func_name1, func_name2, :meth:`func_name`, func_name3
"""
items = []
def parse_item_name(text):
"""Match ':role:`name`' or 'name'"""
m = self._name_rgx.match(text)
if m:
g = m.groups()
if g[1] is None:
return g[3], None
else:
return g[2], g[1]
raise ValueError("%s is not a item name" % text)
def push_item(name, rest):
if not name:
return
name, role = parse_item_name(name)
items.append((name, list(rest), role))
del rest[:]
current_func = None
rest = []
for line in content:
if not line.strip(): continue
m = self._name_rgx.match(line)
if m and line[m.end():].strip().startswith(':'):
push_item(current_func, rest)
current_func, line = line[:m.end()], line[m.end():]
rest = [line.split(':', 1)[1].strip()]
if not rest[0]:
rest = []
elif not line.startswith(' '):
push_item(current_func, rest)
current_func = None
if ',' in line:
for func in line.split(','):
if func.strip():
push_item(func, [])
elif line.strip():
current_func = line
elif current_func is not None:
rest.append(line.strip())