├── .github └── workflows │ └── codeql.yml ├── Makefile ├── _static ├── basic_screenshot.png ├── default.css └── fancy_screenshot.png ├── _templates └── layout.html ├── cheatsheet.rst ├── conf.py ├── custom_look.rst ├── emacs_help.rst ├── extensions.rst ├── getting_started.rst ├── index.rst ├── ipython_directive.rst ├── pyplots └── ellipses.py └── requirements.txt /.github/workflows/codeql.yml: -------------------------------------------------------------------------------- 1 | name: "CodeQL" 2 | 3 | on: 4 | push: 5 | branches: [ "master" ] 6 | pull_request: 7 | branches: [ "master" ] 8 | schedule: 9 | - cron: "0 22 * * 5" 10 | 11 | jobs: 12 | analyze: 13 | name: Analyze 14 | runs-on: ubuntu-latest 15 | permissions: 16 | actions: read 17 | contents: read 18 | security-events: write 19 | 20 | strategy: 21 | fail-fast: false 22 | matrix: 23 | language: [ javascript, python ] 24 | 25 | steps: 26 | - name: Checkout 27 | uses: actions/checkout@v3 28 | 29 | - name: Initialize CodeQL 30 | uses: github/codeql-action/init@v2 31 | with: 32 | languages: ${{ matrix.language }} 33 | queries: +security-and-quality 34 | 35 | - name: Autobuild 36 | uses: github/codeql-action/autobuild@v2 37 | if: ${{ matrix.language == 'javascript' || matrix.language == 'python' }} 38 | 39 | - name: Perform CodeQL Analysis 40 | uses: github/codeql-action/analyze@v2 41 | with: 42 | category: "/language:${{ matrix.language }}" 43 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | PAPER = 8 | 9 | # Internal variables. 10 | PAPEROPT_a4 = -D latex_paper_size=a4 11 | PAPEROPT_letter = -D latex_paper_size=letter 12 | ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 13 | 14 | .PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest 15 | 16 | help: 17 | @echo "Please use \`make ' where is one of" 18 | @echo " html to make standalone HTML files" 19 | @echo " dirhtml to make HTML files named index.html in directories" 20 | @echo " pickle to make pickle files" 21 | @echo " json to make JSON files" 22 | @echo " htmlhelp to make HTML files and a HTML help project" 23 | @echo " qthelp to make HTML files and a qthelp project" 24 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 25 | @echo " changes to make an overview of all changed/added/deprecated items" 26 | @echo " linkcheck to check all external links for integrity" 27 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 28 | 29 | clean: 30 | -rm -rf _build/* 31 | 32 | html: 33 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html 34 | @echo 35 | @echo "Build finished. The HTML pages are in _build/html." 36 | 37 | dirhtml: 38 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml 39 | @echo 40 | @echo "Build finished. The HTML pages are in _build/dirhtml." 41 | 42 | pickle: 43 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle 44 | @echo 45 | @echo "Build finished; now you can process the pickle files." 46 | 47 | json: 48 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json 49 | @echo 50 | @echo "Build finished; now you can process the JSON files." 51 | 52 | htmlhelp: 53 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp 54 | @echo 55 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 56 | ".hhp project file in _build/htmlhelp." 57 | 58 | qthelp: 59 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp 60 | @echo 61 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 62 | ".qhcp project file in _build/qthelp, like this:" 63 | @echo "# qcollectiongenerator _build/qthelp/sampledoc.qhcp" 64 | @echo "To view the help file:" 65 | @echo "# assistant -collectionFile _build/qthelp/sampledoc.qhc" 66 | 67 | latex: 68 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex 69 | @echo 70 | @echo "Build finished; the LaTeX files are in _build/latex." 71 | @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ 72 | "run these through (pdf)latex." 73 | 74 | changes: 75 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes 76 | @echo 77 | @echo "The overview file is in _build/changes." 78 | 79 | linkcheck: 80 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck 81 | @echo 82 | @echo "Link check complete; look for any errors in the above output " \ 83 | "or in _build/linkcheck/output.txt." 84 | 85 | doctest: 86 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest 87 | @echo "Testing of doctests in the sources finished, look at the " \ 88 | "results in _build/doctest/output.txt." 89 | 90 | pdf: latex 91 | cd _build/latex && make all-pdf 92 | 93 | pdf-html: pdf html 94 | cp _build/latex/sampledoc.pdf _build/html 95 | -------------------------------------------------------------------------------- /_static/basic_screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matplotlib/sampledoc/4e60567adca1e63f82e9dbaaedc0b204f00cb48e/_static/basic_screenshot.png -------------------------------------------------------------------------------- /_static/default.css: -------------------------------------------------------------------------------- 1 | /** 2 | * Alternate Sphinx design 3 | * Originally created by Armin Ronacher for Werkzeug, adapted by Georg Brandl. 4 | */ 5 | 6 | body { 7 | font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', 'Verdana', sans-serif; 8 | font-size: 14px; 9 | letter-spacing: -0.01em; 10 | line-height: 150%; 11 | text-align: center; 12 | /*background-color: #AFC1C4; */ 13 | background-color: #BFD1D4; 14 | color: black; 15 | padding: 0; 16 | border: 1px solid #aaa; 17 | 18 | margin: 0px 80px 0px 80px; 19 | min-width: 740px; 20 | } 21 | 22 | a { 23 | color: #CA7900; 24 | text-decoration: none; 25 | } 26 | 27 | a:hover { 28 | color: #2491CF; 29 | } 30 | 31 | pre { 32 | font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; 33 | font-size: 0.95em; 34 | letter-spacing: 0.015em; 35 | padding: 0.5em; 36 | border: 1px solid #ccc; 37 | background-color: #f8f8f8; 38 | } 39 | 40 | td.linenos pre { 41 | padding: 0.5em 0; 42 | border: 0; 43 | background-color: transparent; 44 | color: #aaa; 45 | } 46 | 47 | table.highlighttable { 48 | margin-left: 0.5em; 49 | } 50 | 51 | table.highlighttable td { 52 | padding: 0 0.5em 0 0.5em; 53 | } 54 | 55 | cite, code, tt { 56 | font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; 57 | font-size: 0.95em; 58 | letter-spacing: 0.01em; 59 | } 60 | 61 | hr { 62 | border: 1px solid #abc; 63 | margin: 2em; 64 | } 65 | 66 | tt { 67 | background-color: #f2f2f2; 68 | border-bottom: 1px solid #ddd; 69 | color: #333; 70 | } 71 | 72 | tt.descname { 73 | background-color: transparent; 74 | font-weight: bold; 75 | font-size: 1.2em; 76 | border: 0; 77 | } 78 | 79 | tt.descclassname { 80 | background-color: transparent; 81 | border: 0; 82 | } 83 | 84 | tt.xref { 85 | background-color: transparent; 86 | font-weight: bold; 87 | border: 0; 88 | } 89 | 90 | a tt { 91 | background-color: transparent; 92 | font-weight: bold; 93 | border: 0; 94 | color: #CA7900; 95 | } 96 | 97 | a tt:hover { 98 | color: #2491CF; 99 | } 100 | 101 | dl { 102 | margin-bottom: 15px; 103 | } 104 | 105 | dd p { 106 | margin-top: 0px; 107 | } 108 | 109 | dd ul, dd table { 110 | margin-bottom: 10px; 111 | } 112 | 113 | dd { 114 | margin-top: 3px; 115 | margin-bottom: 10px; 116 | margin-left: 30px; 117 | } 118 | 119 | .refcount { 120 | color: #060; 121 | } 122 | 123 | dt:target, 124 | .highlight { 125 | background-color: #fbe54e; 126 | } 127 | 128 | dl.class, dl.function { 129 | border-top: 2px solid #888; 130 | } 131 | 132 | dl.method, dl.attribute { 133 | border-top: 1px solid #aaa; 134 | } 135 | 136 | dl.glossary dt { 137 | font-weight: bold; 138 | font-size: 1.1em; 139 | } 140 | 141 | pre { 142 | line-height: 120%; 143 | } 144 | 145 | pre a { 146 | color: inherit; 147 | text-decoration: underline; 148 | } 149 | 150 | .first { 151 | margin-top: 0 !important; 152 | } 153 | 154 | div.document { 155 | background-color: white; 156 | text-align: left; 157 | background-image: url(contents.png); 158 | background-repeat: repeat-x; 159 | } 160 | 161 | /* 162 | div.documentwrapper { 163 | width: 100%; 164 | } 165 | */ 166 | 167 | div.clearer { 168 | clear: both; 169 | } 170 | 171 | div.related h3 { 172 | display: none; 173 | } 174 | 175 | div.related ul { 176 | background-image: url(navigation.png); 177 | height: 2em; 178 | list-style: none; 179 | border-top: 1px solid #ddd; 180 | border-bottom: 1px solid #ddd; 181 | margin: 0; 182 | padding-left: 10px; 183 | } 184 | 185 | div.related ul li { 186 | margin: 0; 187 | padding: 0; 188 | height: 2em; 189 | float: left; 190 | } 191 | 192 | div.related ul li.right { 193 | float: right; 194 | margin-right: 5px; 195 | } 196 | 197 | div.related ul li a { 198 | margin: 0; 199 | padding: 0 5px 0 5px; 200 | line-height: 1.75em; 201 | color: #EE9816; 202 | } 203 | 204 | div.related ul li a:hover { 205 | color: #3CA8E7; 206 | } 207 | 208 | div.body { 209 | margin: 0; 210 | padding: 0.5em 20px 20px 20px; 211 | } 212 | 213 | div.bodywrapper { 214 | margin: 0 240px 0 0; 215 | border-right: 1px solid #ccc; 216 | } 217 | 218 | div.body a { 219 | text-decoration: underline; 220 | } 221 | 222 | div.sphinxsidebar { 223 | margin: 0; 224 | padding: 0.5em 15px 15px 0; 225 | width: 210px; 226 | float: right; 227 | text-align: left; 228 | /* margin-left: -100%; */ 229 | } 230 | 231 | div.sphinxsidebar h4, div.sphinxsidebar h3 { 232 | margin: 1em 0 0.5em 0; 233 | font-size: 0.9em; 234 | padding: 0.1em 0 0.1em 0.5em; 235 | color: white; 236 | border: 1px solid #86989B; 237 | background-color: #AFC1C4; 238 | } 239 | 240 | div.sphinxsidebar ul { 241 | padding-left: 1.5em; 242 | margin-top: 7px; 243 | list-style: none; 244 | padding: 0; 245 | line-height: 130%; 246 | } 247 | 248 | div.sphinxsidebar ul ul { 249 | list-style: square; 250 | margin-left: 20px; 251 | } 252 | 253 | p { 254 | margin: 0.8em 0 0.5em 0; 255 | } 256 | 257 | p.rubric { 258 | font-weight: bold; 259 | } 260 | 261 | h1 { 262 | margin: 0; 263 | padding: 0.7em 0 0.3em 0; 264 | font-size: 1.5em; 265 | color: #11557C; 266 | } 267 | 268 | h2 { 269 | margin: 1.3em 0 0.2em 0; 270 | font-size: 1.35em; 271 | padding: 0; 272 | } 273 | 274 | h3 { 275 | margin: 1em 0 -0.3em 0; 276 | font-size: 1.2em; 277 | } 278 | 279 | h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { 280 | color: black!important; 281 | } 282 | 283 | h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor { 284 | display: none; 285 | margin: 0 0 0 0.3em; 286 | padding: 0 0.2em 0 0.2em; 287 | color: #aaa!important; 288 | } 289 | 290 | h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, 291 | h5:hover a.anchor, h6:hover a.anchor { 292 | display: inline; 293 | } 294 | 295 | h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover, 296 | h5 a.anchor:hover, h6 a.anchor:hover { 297 | color: #777; 298 | background-color: #eee; 299 | } 300 | 301 | table { 302 | border-collapse: collapse; 303 | margin: 0 -0.5em 0 -0.5em; 304 | } 305 | 306 | table td, table th { 307 | padding: 0.2em 0.5em 0.2em 0.5em; 308 | } 309 | 310 | div.footer { 311 | background-color: #E3EFF1; 312 | color: #86989B; 313 | padding: 3px 8px 3px 0; 314 | clear: both; 315 | font-size: 0.8em; 316 | text-align: right; 317 | } 318 | 319 | div.footer a { 320 | color: #86989B; 321 | text-decoration: underline; 322 | } 323 | 324 | div.pagination { 325 | margin-top: 2em; 326 | padding-top: 0.5em; 327 | border-top: 1px solid black; 328 | text-align: center; 329 | } 330 | 331 | div.sphinxsidebar ul.toc { 332 | margin: 1em 0 1em 0; 333 | padding: 0 0 0 0.5em; 334 | list-style: none; 335 | } 336 | 337 | div.sphinxsidebar ul.toc li { 338 | margin: 0.5em 0 0.5em 0; 339 | font-size: 0.9em; 340 | line-height: 130%; 341 | } 342 | 343 | div.sphinxsidebar ul.toc li p { 344 | margin: 0; 345 | padding: 0; 346 | } 347 | 348 | div.sphinxsidebar ul.toc ul { 349 | margin: 0.2em 0 0.2em 0; 350 | padding: 0 0 0 1.8em; 351 | } 352 | 353 | div.sphinxsidebar ul.toc ul li { 354 | padding: 0; 355 | } 356 | 357 | div.admonition, div.warning { 358 | font-size: 0.9em; 359 | margin: 1em 0 0 0; 360 | border: 1px solid #86989B; 361 | background-color: #f7f7f7; 362 | } 363 | 364 | div.admonition p, div.warning p { 365 | margin: 0.5em 1em 0.5em 1em; 366 | padding: 0; 367 | } 368 | 369 | div.admonition pre, div.warning pre { 370 | margin: 0.4em 1em 0.4em 1em; 371 | } 372 | 373 | div.admonition p.admonition-title, 374 | div.warning p.admonition-title { 375 | margin: 0; 376 | padding: 0.1em 0 0.1em 0.5em; 377 | color: white; 378 | border-bottom: 1px solid #86989B; 379 | font-weight: bold; 380 | background-color: #AFC1C4; 381 | } 382 | 383 | div.warning { 384 | border: 1px solid #940000; 385 | } 386 | 387 | div.warning p.admonition-title { 388 | background-color: #CF0000; 389 | border-bottom-color: #940000; 390 | } 391 | 392 | div.admonition ul, div.admonition ol, 393 | div.warning ul, div.warning ol { 394 | margin: 0.1em 0.5em 0.5em 3em; 395 | padding: 0; 396 | } 397 | 398 | div.versioninfo { 399 | margin: 1em 0 0 0; 400 | border: 1px solid #ccc; 401 | background-color: #DDEAF0; 402 | padding: 8px; 403 | line-height: 1.3em; 404 | font-size: 0.9em; 405 | } 406 | 407 | 408 | a.headerlink { 409 | color: #c60f0f!important; 410 | font-size: 1em; 411 | margin-left: 6px; 412 | padding: 0 4px 0 4px; 413 | text-decoration: none!important; 414 | visibility: hidden; 415 | } 416 | 417 | h1:hover > a.headerlink, 418 | h2:hover > a.headerlink, 419 | h3:hover > a.headerlink, 420 | h4:hover > a.headerlink, 421 | h5:hover > a.headerlink, 422 | h6:hover > a.headerlink, 423 | dt:hover > a.headerlink { 424 | visibility: visible; 425 | } 426 | 427 | a.headerlink:hover { 428 | background-color: #ccc; 429 | color: white!important; 430 | } 431 | 432 | table.indextable td { 433 | text-align: left; 434 | vertical-align: top; 435 | } 436 | 437 | table.indextable dl, table.indextable dd { 438 | margin-top: 0; 439 | margin-bottom: 0; 440 | } 441 | 442 | table.indextable tr.pcap { 443 | height: 10px; 444 | } 445 | 446 | table.indextable tr.cap { 447 | margin-top: 10px; 448 | background-color: #f2f2f2; 449 | } 450 | 451 | img.toggler { 452 | margin-right: 3px; 453 | margin-top: 3px; 454 | cursor: pointer; 455 | } 456 | 457 | img.inheritance { 458 | border: 0px 459 | } 460 | 461 | form.pfform { 462 | margin: 10px 0 20px 0; 463 | } 464 | 465 | table.contentstable { 466 | width: 90%; 467 | } 468 | 469 | table.contentstable p.biglink { 470 | line-height: 150%; 471 | } 472 | 473 | a.biglink { 474 | font-size: 1.3em; 475 | } 476 | 477 | span.linkdescr { 478 | font-style: italic; 479 | padding-top: 5px; 480 | font-size: 90%; 481 | } 482 | 483 | ul.search { 484 | margin: 10px 0 0 20px; 485 | padding: 0; 486 | } 487 | 488 | ul.search li { 489 | padding: 5px 0 5px 20px; 490 | background-image: url(file.png); 491 | background-repeat: no-repeat; 492 | background-position: 0 7px; 493 | } 494 | 495 | ul.search li a { 496 | font-weight: bold; 497 | } 498 | 499 | ul.search li div.context { 500 | color: #888; 501 | margin: 2px 0 0 30px; 502 | text-align: left; 503 | } 504 | 505 | ul.keywordmatches li.goodmatch a { 506 | font-weight: bold; 507 | } 508 | -------------------------------------------------------------------------------- /_static/fancy_screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matplotlib/sampledoc/4e60567adca1e63f82e9dbaaedc0b204f00cb48e/_static/fancy_screenshot.png -------------------------------------------------------------------------------- /_templates/layout.html: -------------------------------------------------------------------------------- 1 | {% extends "!layout.html" %} 2 | 3 | 4 | {% block rootrellink %} 5 |
  • home| 
    • 6 |
  • search| 
    • 7 | {% endblock %} 8 | 9 | 10 | {% block relbar1 %} 11 | 12 |
    13 |

    Sampledoc

     14 |
    15 | {{ super() }} 16 | {% endblock %} 17 | 18 | {# put the sidebar before the body #} 19 | {% block sidebar1 %}{{ sidebar() }}{% endblock %} 20 | {% block sidebar2 %}{% endblock %} 21 | -------------------------------------------------------------------------------- /cheatsheet.rst: -------------------------------------------------------------------------------- 1 | .. _cheat-sheet: 2 | 3 | ****************** 4 | Sphinx cheat sheet 5 | ****************** 6 | 7 | Here is a quick and dirty cheat sheet for some common stuff you want 8 | to do in sphinx and ReST. You can see the literal source for this 9 | file at :ref:`cheatsheet-literal`. 10 | 11 | 12 | .. _formatting-text: 13 | 14 | Formatting text 15 | =============== 16 | 17 | You use inline markup to make text *italics*, **bold**, or ``monotype``. 18 | 19 | You can represent code blocks fairly easily:: 20 | 21 | import numpy as np 22 | x = np.random.rand(12) 23 | 24 | Or literally include code: 25 | 26 | .. literalinclude:: pyplots/ellipses.py 27 | 28 | .. _making-a-list: 29 | 30 | Making a list 31 | ============= 32 | 33 | It is easy to make lists in rest 34 | 35 | Bullet points 36 | ------------- 37 | 38 | This is a subsection making bullet points 39 | 40 | * point A 41 | 42 | * point B 43 | 44 | * point C 45 | 46 | 47 | Enumerated points 48 | ------------------ 49 | 50 | This is a subsection making numbered points 51 | 52 | #. point A 53 | 54 | #. point B 55 | 56 | #. point C 57 | 58 | 59 | .. _making-a-table: 60 | 61 | Making a table 62 | ============== 63 | 64 | This shows you how to make a table -- if you only want to make a list see :ref:`making-a-list`. 65 | 66 | ================== ============ 67 | Name Age 68 | ================== ============ 69 | John D Hunter 40 70 | Cast of Thousands 41 71 | And Still More 42 72 | ================== ============ 73 | 74 | .. _making-links: 75 | 76 | Making links 77 | ============ 78 | 79 | It is easy to make a link to `yahoo `_ or to some 80 | section inside this document (see :ref:`making-a-table`) or another 81 | document. 82 | 83 | You can also reference classes, modules, functions, etc that are 84 | documented using the sphinx `autodoc 85 | `_ facilites. For example, 86 | see the module :mod:`matplotlib.backend_bases` documentation, or the 87 | class :class:`~matplotlib.backend_bases.LocationEvent`, or the method 88 | :meth:`~matplotlib.backend_bases.FigureCanvasBase.mpl_connect`. 89 | 90 | 91 | 92 | .. _cheatsheet-literal: 93 | 94 | This file 95 | ========= 96 | 97 | .. literalinclude:: cheatsheet.rst 98 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # sampledoc documentation build configuration file, created by 4 | # sphinx-quickstart on Tue Aug 11 05:04:40 2009. 5 | # 6 | # This file is execfile()d with the current directory set to its containing dir. 7 | # 8 | # Note that not all possible configuration values are present in this 9 | # autogenerated file. 10 | # 11 | # All configuration values have a default; values that are commented out 12 | # serve to show the default. 13 | 14 | import sys, os 15 | 16 | # If your extensions are in another directory, add it here. If the directory 17 | # is relative to the documentation root, use os.path.abspath to make it 18 | # absolute, like shown here. 19 | # sys.path.append(os.path.abspath('sphinxext')) 20 | 21 | # -- General configuration ----------------------------------------------------- 22 | 23 | # Add any Sphinx extension module names here, as strings. They can be extensions 24 | # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 25 | extensions = ['matplotlib.sphinxext.only_directives', 26 | 'matplotlib.sphinxext.plot_directive', 27 | 'IPython.sphinxext.ipython_directive', 28 | 'IPython.sphinxext.ipython_console_highlighting', 29 | 'sphinx.ext.mathjax', 30 | 'sphinx.ext.autodoc', 31 | 'sphinx.ext.doctest', 32 | 'sphinx.ext.inheritance_diagram', 33 | 'numpydoc'] 34 | 35 | # Add any paths that contain templates here, relative to this directory. 36 | templates_path = ['_templates'] 37 | 38 | # The suffix of source filenames. 39 | source_suffix = '.rst' 40 | 41 | # The encoding of source files. 42 | #source_encoding = 'utf-8' 43 | 44 | # The master toctree document. 45 | master_doc = 'index' 46 | 47 | # General information about the project. 48 | project = u'sampledoc' 49 | copyright = u'2009, John Hunter, Fernando Perez, Michael Droettboom' 50 | 51 | # The version info for the project you're documenting, acts as replacement for 52 | # |version| and |release|, also used in various other places throughout the 53 | # built documents. 54 | # 55 | # The short X.Y version. 56 | version = '1.0' 57 | # The full version, including alpha/beta/rc tags. 58 | release = '1.0' 59 | 60 | # The language for content autogenerated by Sphinx. Refer to documentation 61 | # for a list of supported languages. 62 | #language = None 63 | 64 | # There are two options for replacing |today|: either, you set today to some 65 | # non-false value, then it is used: 66 | #today = '' 67 | # Else, today_fmt is used as the format for a strftime call. 68 | #today_fmt = '%B %d, %Y' 69 | 70 | # List of documents that shouldn't be included in the build. 71 | #unused_docs = [] 72 | 73 | # List of directories, relative to source directory, that shouldn't be searched 74 | # for source files. 75 | exclude_trees = ['_build'] 76 | 77 | # The reST default role (used for this markup: `text`) to use for all documents. 78 | #default_role = None 79 | 80 | # If true, '()' will be appended to :func: etc. cross-reference text. 81 | #add_function_parentheses = True 82 | 83 | # If true, the current module name will be prepended to all description 84 | # unit titles (such as .. function::). 85 | #add_module_names = True 86 | 87 | # If true, sectionauthor and moduleauthor directives will be shown in the 88 | # output. They are ignored by default. 89 | #show_authors = False 90 | 91 | # The name of the Pygments (syntax highlighting) style to use. 92 | pygments_style = 'sphinx' 93 | 94 | # A list of ignored prefixes for module index sorting. 95 | #modindex_common_prefix = [] 96 | 97 | 98 | # -- Options for HTML output --------------------------------------------------- 99 | 100 | # The theme to use for HTML and HTML Help pages. Major themes that come with 101 | # Sphinx are currently 'default' and 'sphinxdoc'. 102 | html_theme = 'sphinxdoc' 103 | 104 | # Theme options are theme-specific and customize the look and feel of a theme 105 | # further. For a list of options available for each theme, see the 106 | # documentation. 107 | #html_theme_options = {} 108 | 109 | # Add any paths that contain custom themes here, relative to this directory. 110 | #html_theme_path = [] 111 | 112 | # The name for this set of Sphinx documents. If None, it defaults to 113 | # " v documentation". 114 | #html_title = None 115 | 116 | # A shorter title for the navigation bar. Default is the same as html_title. 117 | #html_short_title = None 118 | 119 | # The name of an image file (relative to this directory) to place at the top 120 | # of the sidebar. 121 | #html_logo = None 122 | 123 | # The name of an image file (within the static path) to use as favicon of the 124 | # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 125 | # pixels large. 126 | #html_favicon = None 127 | 128 | # Add any paths that contain custom static files (such as style sheets) here, 129 | # relative to this directory. They are copied after the builtin static files, 130 | # so a file named "default.css" will overwrite the builtin "default.css". 131 | html_static_path = ['_static'] 132 | 133 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 134 | # using the given strftime format. 135 | #html_last_updated_fmt = '%b %d, %Y' 136 | 137 | # If true, SmartyPants will be used to convert quotes and dashes to 138 | # typographically correct entities. 139 | #html_use_smartypants = True 140 | 141 | # Custom sidebar templates, maps document names to template names. 142 | #html_sidebars = {} 143 | 144 | # Additional templates that should be rendered to pages, maps page names to 145 | # template names. 146 | #html_additional_pages = {} 147 | 148 | # If false, no module index is generated. 149 | #html_use_modindex = True 150 | 151 | # If false, no index is generated. 152 | #html_use_index = True 153 | 154 | # If true, the index is split into individual pages for each letter. 155 | #html_split_index = False 156 | 157 | # If true, links to the reST sources are added to the pages. 158 | #html_show_sourcelink = True 159 | 160 | # If true, an OpenSearch description file will be output, and all pages will 161 | # contain a tag referring to it. The value of this option must be the 162 | # base URL from which the finished HTML is served. 163 | #html_use_opensearch = '' 164 | 165 | # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). 166 | #html_file_suffix = '' 167 | 168 | # Output file base name for HTML help builder. 169 | htmlhelp_basename = 'sampledocdoc' 170 | 171 | 172 | # -- Options for LaTeX output -------------------------------------------------- 173 | 174 | # The paper size ('letter' or 'a4'). 175 | #latex_paper_size = 'letter' 176 | 177 | # The font size ('10pt', '11pt' or '12pt'). 178 | #latex_font_size = '10pt' 179 | 180 | # Grouping the document tree into LaTeX files. List of tuples 181 | # (source start file, target name, title, author, documentclass [howto/manual]). 182 | latex_documents = [ 183 | ('index', 'sampledoc.tex', u'sampledoc Documentation', 184 | u'John Hunter, Fernando Perez, Michael Droettboom', 'manual'), 185 | ] 186 | 187 | # The name of an image file (relative to this directory) to place at the top of 188 | # the title page. 189 | #latex_logo = None 190 | 191 | # For "manual" documents, if this is true, then toplevel headings are parts, 192 | # not chapters. 193 | #latex_use_parts = False 194 | 195 | # Additional stuff for the LaTeX preamble. 196 | #latex_preamble = '' 197 | 198 | # Documents to append as an appendix to all manuals. 199 | #latex_appendices = [] 200 | 201 | # If false, no module index is generated. 202 | #latex_use_modindex = True 203 | -------------------------------------------------------------------------------- /custom_look.rst: -------------------------------------------------------------------------------- 1 | .. _custom_look: 2 | 3 | 4 | ****************************************** 5 | Customizing the look and feel of the site 6 | ****************************************** 7 | 8 | The `sphinx `_ site itself looks better than 9 | the sites created with the default css, so here we'll 10 | invoke T. S. Eliot's maxim "Talent imitates, but genius steals" and 11 | grab their css and part of their layout. As before, you can either 12 | get the required files :file:`_static/default.css` and 13 | :file:`_templates/layout.html` from the website or git (see 14 | :ref:`fetching-the-data`). Since I did a git clone before, I will 15 | just copy the stuff I need from there:: 16 | 17 | home:~/tmp/sampledoc> cp ../sampledoc_tut/_static/default.css _static/ 18 | home:~/tmp/sampledoc> cp ../sampledoc_tut/_templates/layout.html _templates/ 19 | home:~/tmp/sampledoc> ls _static/ _templates/ 20 | _static/: 21 | basic_screenshot.png default.css 22 | 23 | _templates/: 24 | layout.html 25 | 26 | Sphinx will automatically pick up the css and layout html files since 27 | we put them in the default places with the default names, but we have 28 | to manually edit the top of :file:`layout.html` to style the title. 29 | Let's take a look at the layout file: the first part puts a horizontal 30 | navigation bar at the top of our page, like you see on the Sphinx 31 | and `matplotlib `_ sites, the second part 32 | includes a title that when we click on it will take us `home` and the last part 33 | moves the vertical navigation panels to the right side of the page:: 34 | 35 | {% extends "!layout.html" %} 36 | 37 | 38 | {% block rootrellink %} 39 |
  • home| 
    • 40 |
  • search| 
    • 41 | {% endblock %} 42 | 43 | 44 | {% block relbar1 %} 45 | 46 |
    47 |

    Sampledoc

     48 |
    49 | {{ super() }} 50 | {% endblock %} 51 | 52 | {# put the sidebar before the body #} 53 | {% block sidebar1 %}{{ sidebar() }}{% endblock %} 54 | {% block sidebar2 %}{% endblock %} 55 | 56 | Lastly, we need to modify the html theme in :file:`sampledoc/conf.py`:: 57 | 58 | html_theme = 'sphinxdoc' 59 | 60 | Once you rebuild the site with a ``make html`` and reload the page in your browser, you should see a fancier site that looks like this 61 | 62 | .. image:: _static/fancy_screenshot.png 63 | -------------------------------------------------------------------------------- /emacs_help.rst: -------------------------------------------------------------------------------- 1 | .. _working-with-emacs: 2 | 3 | ******************* 4 | Emacs ReST support 5 | ******************* 6 | 7 | Emacs helpers 8 | ============= 9 | 10 | There is an emacs mode `rst.el 11 | `_ which 12 | automates many important ReST tasks like building and updateing 13 | table-of-contents, and promoting or demoting section headings. Here 14 | is the basic ``.emacs`` configuration:: 15 | 16 | (require 'rst) 17 | (setq auto-mode-alist 18 | (append '(("\\.txt$" . rst-mode) 19 | ("\\.rst$" . rst-mode) 20 | ("\\.rest$" . rst-mode)) auto-mode-alist)) 21 | 22 | 23 | Some helpful functions:: 24 | 25 | C-c TAB - rst-toc-insert 26 | 27 | Insert table of contents at point 28 | 29 | C-c C-u - rst-toc-update 30 | 31 | Update the table of contents at point 32 | 33 | C-c C-l rst-shift-region-left 34 | 35 | Shift region to the left 36 | 37 | C-c C-r rst-shift-region-right 38 | 39 | Shift region to the right 40 | 41 | -------------------------------------------------------------------------------- /extensions.rst: -------------------------------------------------------------------------------- 1 | .. _extensions: 2 | 3 | **************************************************** 4 | Sphinx extensions for embedded plots, math and more 5 | **************************************************** 6 | 7 | Sphinx is written in python, and supports the ability to write custom 8 | extensions. We've written a few for the matplotlib documentation, 9 | some of which are part of matplotlib itself in the 10 | matplotlib.sphinxext module, some of which are included only in the 11 | sphinx doc directory, and there are other extensions written by other 12 | groups, eg numpy and ipython. We're collecting these in this tutorial 13 | and showing you how to install and use them for your own project. 14 | First let's grab the python extension files from the :file:`sphinxext` 15 | directory from git (see :ref:`fetching-the-data`), and install them in 16 | our :file:`sampledoc` project :file:`sphinxext` directory:: 17 | 18 | home:~/tmp/sampledoc> mkdir sphinxext 19 | home:~/tmp/sampledoc> cp ../sampledoc_tut/sphinxext/*.py sphinxext/ 20 | home:~/tmp/sampledoc> ls sphinxext/ 21 | apigen.py docscrape.py docscrape_sphinx.py numpydoc.py 22 | 23 | In addition to the builtin matplotlib extensions for embedding pyplot 24 | plots and rendering math with matplotlib's native math engine, we also 25 | have extensions for syntax highlighting ipython sessions, making 26 | inhertiance diagrams, and more. 27 | 28 | We need to inform sphinx of our new extensions in the :file:`conf.py` 29 | file by adding the following. First we tell it where to find the extensions:: 30 | 31 | # If your extensions are in another directory, add it here. If the 32 | # directory is relative to the documentation root, use 33 | # os.path.abspath to make it absolute, like shown here. 34 | sys.path.append(os.path.abspath('sphinxext')) 35 | 36 | And then we tell it what extensions to load:: 37 | 38 | # Add any Sphinx extension module names here, as strings. They can be extensions 39 | # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 40 | extensions = ['matplotlib.sphinxext.only_directives', 41 | 'matplotlib.sphinxext.plot_directive', 42 | 'IPython.sphinxext.ipython_directive', 43 | 'IPython.sphinxext.ipython_console_highlighting', 44 | 'sphinx.ext.mathjax', 45 | 'sphinx.ext.autodoc', 46 | 'sphinx.ext.doctest', 47 | 'sphinx.ext.inheritance_diagram', 48 | 'numpydoc'] 49 | 50 | Now let's look at some of these in action. You can see the literal 51 | source for this file at :ref:`extensions-literal`. 52 | 53 | .. _ipython-highlighting: 54 | 55 | ipython sessions 56 | ================ 57 | 58 | Michael Droettboom contributed a sphinx extension which does `pygments 59 | `_ syntax highlighting on `ipython 60 | `_ sessions. Just use ipython as the 61 | language in the ``sourcecode`` directive:: 62 | 63 | .. sourcecode:: ipython 64 | 65 | In [69]: lines = plot([1,2,3]) 66 | 67 | In [70]: setp(lines) 68 | alpha: float 69 | animated: [True | False] 70 | antialiased or aa: [True | False] 71 | ...snip 72 | 73 | 74 | and you will get the syntax highlighted output below. 75 | 76 | .. sourcecode:: ipython 77 | 78 | In [69]: lines = plot([1,2,3]) 79 | 80 | In [70]: setp(lines) 81 | alpha: float 82 | animated: [True | False] 83 | antialiased or aa: [True | False] 84 | ...snip 85 | 86 | This support is included in this template, but will also be included 87 | in a future version of Pygments by default. 88 | 89 | .. _using-math: 90 | 91 | Using math 92 | ========== 93 | 94 | In sphinx you can include inline math :math:`x\leftarrow y\ x\forall 95 | y\ x-y` or display math 96 | 97 | .. math:: 98 | 99 | W^{3\beta}_{\delta_1 \rho_1 \sigma_2} = U^{3\beta}_{\delta_1 \rho_1} + \frac{1}{8 \pi 2} \int^{\alpha_2}_{\alpha_2} d \alpha^\prime_2 \left[\frac{ U^{2\beta}_{\delta_1 \rho_1} - \alpha^\prime_2U^{1\beta}_{\rho_1 \sigma_2} }{U^{0\beta}_{\rho_1 \sigma_2}}\right] 100 | 101 | To include math in your document, just use the math directive; here is 102 | a simpler equation:: 103 | 104 | .. math:: 105 | 106 | W^{3\beta}_{\delta_1 \rho_1 \sigma_2} \approx U^{3\beta}_{\delta_1 \rho_1} 107 | 108 | which is rendered as 109 | 110 | .. math:: 111 | 112 | W^{3\beta}_{\delta_1 \rho_1 \sigma_2} \approx U^{3\beta}_{\delta_1 \rho_1} 113 | 114 | Recent versions of Sphinx include built-in support for math. 115 | There are three flavors: 116 | 117 | - sphinx.ext.imgmath: uses dvipng to render the equation 118 | 119 | - sphinx.ext.mathjax: renders the math in the browser using Javascript 120 | 121 | - sphinx.ext.jsmath: it's an older code, but it checks out 122 | 123 | Additionally, matplotlib has its own math support: 124 | 125 | - matplotlib.sphinxext.mathmpl 126 | 127 | See the matplotlib `mathtext guide 128 | `_ for lots 129 | more information on writing mathematical expressions in matplotlib. 130 | 131 | .. _pyplots: 132 | 133 | Inserting matplotlib plots 134 | ========================== 135 | 136 | Inserting automatically-generated plots is easy. Simply put the 137 | script to generate the plot in the :file:`pyplots` directory, and 138 | refer to it using the ``plot`` directive. First make a 139 | :file:`pyplots` directory at the top level of your project (next to 140 | :``conf.py``) and copy the :file:`ellipses.py`` file into it:: 141 | 142 | home:~/tmp/sampledoc> mkdir pyplots 143 | home:~/tmp/sampledoc> cp ../sampledoc_tut/pyplots/ellipses.py pyplots/ 144 | 145 | 146 | You can refer to this file in your sphinx documentation; by default it 147 | will just inline the plot with links to the source and PF and high 148 | resolution PNGS. To also include the source code for the plot in the 149 | document, pass the ``include-source`` parameter:: 150 | 151 | .. plot:: pyplots/ellipses.py 152 | :include-source: 153 | 154 | In the HTML version of the document, the plot includes links to the 155 | original source code, a high-resolution PNG and a PDF. In the PDF 156 | version of the document, the plot is included as a scalable PDF. 157 | 158 | .. plot:: pyplots/ellipses.py 159 | :include-source: 160 | 161 | 162 | You can also inline code for plots directly, and the code will be 163 | executed at documentation build time and the figure inserted into your 164 | docs; the following code:: 165 | 166 | .. plot:: 167 | 168 | import matplotlib.pyplot as plt 169 | import numpy as np 170 | x = np.random.randn(1000) 171 | plt.hist( x, 20) 172 | plt.grid() 173 | plt.title(r'Normal: $\mu=%.2f, \sigma=%.2f$'%(x.mean(), x.std())) 174 | plt.show() 175 | 176 | produces this output: 177 | 178 | .. plot:: 179 | 180 | import matplotlib.pyplot as plt 181 | import numpy as np 182 | x = np.random.randn(1000) 183 | plt.hist( x, 20) 184 | plt.grid() 185 | plt.title(r'Normal: $\mu=%.2f, \sigma=%.2f$'%(x.mean(), x.std())) 186 | plt.show() 187 | 188 | 189 | See the matplotlib `pyplot tutorial 190 | `_ and 191 | the `gallery `_ for 192 | lots of examples of matplotlib plots. 193 | 194 | Inheritance diagrams 195 | ==================== 196 | 197 | Inheritance diagrams can be inserted directly into the document by 198 | providing a list of class or module names to the 199 | ``inheritance-diagram`` directive. 200 | 201 | For example:: 202 | 203 | .. inheritance-diagram:: codecs 204 | 205 | produces: 206 | 207 | .. inheritance-diagram:: codecs 208 | 209 | 210 | See the :ref:`ipython_directive` for a tutorial on embedding stateful, 211 | matplotlib aware ipython sessions into your rest docs with multiline 212 | and doctest support. 213 | 214 | .. _extensions-literal: 215 | 216 | This file 217 | ========= 218 | 219 | .. literalinclude:: extensions.rst 220 | 221 | 222 | -------------------------------------------------------------------------------- /getting_started.rst: -------------------------------------------------------------------------------- 1 | .. _getting_started: 2 | 3 | 4 | *************** 5 | Getting started 6 | *************** 7 | 8 | .. _installing-docdir: 9 | 10 | Installing your doc directory 11 | ============================= 12 | 13 | You may already have sphinx `sphinx `_ 14 | installed -- you can check by doing:: 15 | 16 | python -c 'import sphinx' 17 | 18 | If that fails grab the latest version of and install it with:: 19 | 20 | > sudo easy_install -U Sphinx 21 | 22 | Now you are ready to build a template for your docs, using 23 | sphinx-quickstart:: 24 | 25 | > sphinx-quickstart 26 | 27 | accepting most of the defaults. I choose "sampledoc" as the name of my 28 | project. cd into your new directory and check the contents:: 29 | 30 | home:~/tmp/sampledoc> ls 31 | Makefile _static conf.py 32 | _build _templates index.rst 33 | 34 | The index.rst is the master ReST for your project, but before adding 35 | anything, let's see if we can build some html:: 36 | 37 | make html 38 | 39 | If you now point your browser to :file:`_build/html/index.html`, you 40 | should see a basic sphinx site. 41 | 42 | .. image:: _static/basic_screenshot.png 43 | 44 | .. _fetching-the-data: 45 | 46 | Fetching the data 47 | ----------------- 48 | 49 | Now we will start to customize out docs. Grab a couple of files from 50 | the `web site `_ 51 | or git. You will need :file:`getting_started.rst` and 52 | :file:`_static/basic_screenshot.png`. All of the files live in the 53 | "completed" version of this tutorial, but since this is a tutorial, 54 | we'll just grab them one at a time, so you can learn what needs to be 55 | changed where. Since we have more files to come, I'm going to grab 56 | the whole git directory and just copy the files I need over for now. 57 | First, I'll cd up back into the directory containing my project, check 58 | out the "finished" product from git, and then copy in just the files I 59 | need into my :file:`sampledoc` directory:: 60 | 61 | home:~/tmp/sampledoc> pwd 62 | /Users/jdhunter/tmp/sampledoc 63 | home:~/tmp/sampledoc> cd .. 64 | home:~/tmp> git clone https://github.com/matplotlib/sampledoc.git tutorial 65 | Cloning into 'tutorial'... 66 | remote: Counting objects: 87, done. 67 | remote: Compressing objects: 100% (43/43), done. 68 | remote: Total 87 (delta 45), reused 83 (delta 41) 69 | Unpacking objects: 100% (87/87), done. 70 | Checking connectivity... done 71 | home:~/tmp> cp tutorial/getting_started.rst sampledoc/ 72 | home:~/tmp> cp tutorial/_static/basic_screenshot.png sampledoc/_static/ 73 | 74 | The last step is to modify :file:`index.rst` to include the 75 | :file:`getting_started.rst` file (be careful with the indentation, the 76 | "g" in "getting_started" should line up with the ':' in ``:maxdepth``:: 77 | 78 | Contents: 79 | 80 | .. toctree:: 81 | :maxdepth: 2 82 | 83 | getting_started.rst 84 | 85 | and then rebuild the docs:: 86 | 87 | cd sampledoc 88 | make html 89 | 90 | 91 | When you reload the page by refreshing your browser pointing to 92 | :file:`_build/html/index.html`, you should see a link to the 93 | "Getting Started" docs, and in there this page with the screenshot. 94 | `Voila!` 95 | 96 | We can also use the image directive in :file:`index.rst` to include to the screenshot above 97 | with:: 98 | 99 | .. image:: 100 | _static/basic_screenshot.png 101 | 102 | 103 | Next we'll customize the look and feel of our site to give it a logo, 104 | some custom css, and update the navigation panels to look more like 105 | the `sphinx `_ site itself -- see 106 | :ref:`custom_look`. 107 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | .. sampledoc documentation master file, created by 2 | sphinx-quickstart on Tue Aug 11 05:04:40 2009. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | sampledoc tutorial 7 | ================== 8 | 9 | This is a tutorial introduction to quickly get you up and running with 10 | your own sphinx documentation system. We'll cover installing sphinx, 11 | customizing the look and feel, using custom extensions for embedding 12 | plots, inheritance diagrams, syntax highlighted ipython sessions and 13 | more. If you follow along the tutorial, you'll start with nothing and 14 | end up with this site -- it's the bootstrapping documentation tutorial 15 | that writes itself! 16 | 17 | The source code for this tutorial lives in mpl git (see 18 | :ref:`fetching-the-data`). 19 | 20 | .. only:: html 21 | 22 | You can also grab a hardcopy of the `sampledoc PDF `_ 23 | 24 | .. toctree:: 25 | :maxdepth: 2 26 | 27 | getting_started.rst 28 | custom_look.rst 29 | extensions.rst 30 | ipython_directive.rst 31 | cheatsheet.rst 32 | emacs_help.rst 33 | 34 | Indices and tables 35 | ================== 36 | 37 | * :ref:`genindex` 38 | * :ref:`modindex` 39 | * :ref:`search` 40 | 41 | -------------------------------------------------------------------------------- /ipython_directive.rst: -------------------------------------------------------------------------------- 1 | .. _ipython_directive: 2 | 3 | ================= 4 | IPython Directive 5 | ================= 6 | 7 | The IPython directive is a stateful IPython shell for embedding in 8 | Sphinx documents. It knows about standard IPython prompts, and 9 | extracts the input and output lines. These prompts will be renumbered 10 | starting at ``1``. The inputs will be fed to an embedded IPython 11 | interpreter and the outputs from that interpreter will be inserted as 12 | well. For example, code blocks like the following:: 13 | 14 | .. ipython:: 15 | 16 | In [136]: x = 2 17 | 18 | In [137]: x**3 19 | Out[137]: 8 20 | 21 | will be rendered as 22 | 23 | .. ipython:: 24 | 25 | In [136]: x = 2 26 | 27 | In [137]: x**3 28 | Out[137]: 8 29 | 30 | .. note:: 31 | 32 | This tutorial should be read side-by-side with the Sphinx source 33 | for this document (see :ref:`ipython_literal`) because otherwise 34 | you will see only the rendered output and not the code that 35 | generated it. Excepting the example above, we will not in general 36 | be showing the literal reST in this document that generates the 37 | rendered output. 38 | 39 | 40 | The state from previous sessions is stored, and standard error is 41 | trapped. At doc build time, IPython's output and std err will be 42 | inserted, and prompts will be renumbered. So the prompt below should 43 | be renumbered in the rendered docs, and pick up where the block above 44 | left off. 45 | 46 | .. ipython:: 47 | 48 | In [1]: z = x * 3 # x is recalled from previous block 49 | 50 | In [2]: z 51 | 52 | In [3]: print(z) 53 | 54 | In [4]: q = z[) # this is a syntax error -- we trap exceptions 55 | 56 | The embedded interpreter supports some limited markup. For example, 57 | you can put comments in your IPython sessions, which are reported 58 | verbatim. There are some handy "pseudo-decorators" that let you 59 | doctest the output. The inputs are fed to an embedded IPython 60 | session and the outputs from the IPython session are inserted into 61 | your doc. If the output in your doc and in the IPython session don't 62 | match on a doctest assertion, an error will be raised 63 | 64 | .. ipython:: 65 | 66 | In [1]: x = 'hello world' 67 | 68 | # this will raise an error if the IPython output is different 69 | @doctest 70 | In [2]: x.upper() 71 | Out[2]: 'HELLO WORLD' 72 | 73 | # some readline features cannot be supported, so we allow 74 | # "verbatim" blocks, which are dumped in verbatim except prompts 75 | # are continuously numbered 76 | @verbatim 77 | In [3]: x.st 78 | x.startswith x.strip 79 | 80 | Multi-line input is supported. 81 | 82 | .. ipython:: 83 | 84 | In [1]: url = ('https://example.com?s=CROX&d=9&e=22&f=2009&' 85 | ...: 'g=d&a=1&br=8&c=2006&ignore=.csv') 86 | ...: 87 | 88 | In [2]: print(url.split('&')) 89 | 90 | In [3]: import urllib 91 | 92 | You can do doctesting on multi-line output as well. Just be careful 93 | when using non-deterministic inputs like random numbers in the IPython 94 | directive, because your inputs are run through a live interpreter, so 95 | if you are doctesting random output you will get an error. Here we 96 | "seed" the random number generator for deterministic output, and we 97 | suppress the seed line so it doesn't show up in the rendered output 98 | 99 | .. ipython:: 100 | 101 | In [1]: import numpy.random 102 | 103 | @suppress 104 | In [2]: numpy.random.seed(2358) 105 | 106 | @doctest 107 | In [3]: numpy.random.rand(10, 2) 108 | Out[3]: 109 | array([[0.64524308, 0.59943846], 110 | [0.47102322, 0.8715456 ], 111 | [0.29370834, 0.74776844], 112 | [0.99539577, 0.1313423 ], 113 | [0.16250302, 0.21103583], 114 | [0.81626524, 0.1312433 ], 115 | [0.67338089, 0.72302393], 116 | [0.7566368 , 0.07033696], 117 | [0.22591016, 0.77731835], 118 | [0.0072729 , 0.34273127]]) 119 | 120 | Another demonstration of multi-line input and output 121 | 122 | .. ipython:: 123 | 124 | In [1]: print(x) 125 | 126 | In [2]: for i in range(10): 127 | ...: print(i) 128 | ...: 129 | 130 | Most of the "pseudo-decorators" can be used as options to IPython 131 | mode. For example, to setup ``matplotlib`` but suppress the output, 132 | you can do. This will not show up in the rendered docs, but the commands 133 | will be executed in the embedded interpreter and subsequent line numbers 134 | will be incremented to reflect the inputs:: 135 | 136 | .. ipython:: 137 | :suppress: 138 | 139 | In [1]: import matplotlib.pyplot as plt 140 | 141 | In [2]: plt.ion() 142 | 143 | .. ipython:: 144 | :suppress: 145 | 146 | In [1]: import matplotlib.pyplot as plt 147 | 148 | In [2]: plt.ion() 149 | 150 | Likewise, you can set the ``:doctest:`` or ``:verbatim:`` Sphinx options to 151 | apply these settings to the entire block. For example, 152 | 153 | .. ipython:: 154 | :verbatim: 155 | 156 | In [1]: cd mpl/examples/ 157 | /home/jdhunter/mpl/examples 158 | 159 | In [2]: pwd 160 | Out[2]: '/home/jdhunter/mpl/examples' 161 | 162 | In [3]: cd mpl/examples/ 163 | mpl/examples/animation/ mpl/examples/misc/ 164 | mpl/examples/api/ mpl/examples/mplot3d/ 165 | mpl/examples/axes_grid/ mpl/examples/pylab_examples/ 166 | mpl/examples/event_handling/ mpl/examples/widgets 167 | 168 | In [4]: cd mpl/examples/widgets/ 169 | /home/jdhunter/mpl/examples/widgets 170 | 171 | In [5]: !wc * 172 | 2 12 77 README.txt 173 | 40 97 884 buttons.py 174 | 26 90 712 check_buttons.py 175 | 19 52 416 cursor.py 176 | 180 404 4882 menu.py 177 | 16 45 337 multicursor.py 178 | 36 106 916 radio_buttons.py 179 | 48 226 2082 rectangle_selector.py 180 | 43 118 1063 slider_demo.py 181 | 40 124 1088 span_selector.py 182 | 450 1274 12457 total 183 | 184 | You can create one or more plots and insert them with the 185 | ``@savefig`` decorator. 186 | 187 | .. ipython:: 188 | 189 | @savefig plot_simple.png width=4in 190 | In [1]: plt.plot([1,2,3]); 191 | 192 | # use a semicolon to suppress the output 193 | @savefig hist_simple.png width=4in 194 | In [2]: plt.hist(np.random.randn(10000), 100); 195 | 196 | In a subsequent session, we can update the current figure with some 197 | text, and then resave 198 | 199 | .. ipython:: 200 | 201 | In [1]: plt.ylabel('number') 202 | 203 | In [2]: plt.title('normal distribution') 204 | 205 | @savefig hist_with_text.png width=4in align=center 206 | In [3]: plt.grid(True) 207 | 208 | Pseudo-Decorators 209 | ================= 210 | 211 | Here are the supported decorators, and any optional arguments they 212 | take. Some of the decorators can be used as options to the entire 213 | block (eg ``verbatim`` and ``suppress``), and some only apply to the 214 | line just below them (eg ``savefig``). 215 | 216 | ``@suppress`` 217 | 218 | execute the IPython input block, but suppress the input and output 219 | block from the rendered output. Also, can be applied to the entire 220 | ``..ipython`` block as a directive option with ``:suppress:``. 221 | 222 | ``@verbatim`` 223 | 224 | insert the input and output block in verbatim, but auto-increment 225 | the line numbers. Internally, the interpreter will be fed an empty 226 | string, so it is a no-op that keeps line numbering consistent. 227 | Also, can be applied to the entire ``..ipython`` block as a 228 | directive option with ``:verbatim:``. 229 | 230 | ``@savefig OUTFILE [IMAGE_OPTIONS]`` 231 | 232 | save the figure to the static directory and insert it into the 233 | document, possibly binding it into a minipage and/or putting 234 | code/figure label/references to associate the code and the 235 | figure. Takes args to pass to the image directive (*scale*, 236 | *width*, etc can be kwargs); see `image options 237 | `_ 238 | for details. 239 | 240 | ``@doctest`` 241 | 242 | Compare the pasted in output in the IPython block with the output 243 | generated at doc build time, and raise errors if they don’t 244 | match. Also, can be applied to the entire ``..ipython`` block as a 245 | directive option with ``:doctest:``. 246 | 247 | Enabling IPython Directive 248 | ========================== 249 | 250 | To enable the IPython directive(s) in your Sphinx documentation, 251 | you'll need to have ``IPython`` installed and include the following 252 | in your Sphinx configuration (``conf.py``): 253 | 254 | .. code-block:: python 255 | 256 | extensions = [ 257 | 'IPython.sphinxext.ipython_directive', 258 | 'IPython.sphinxext.ipython_console_highlighting', 259 | ... 260 | ] 261 | 262 | .. _ipython_literal: 263 | 264 | Sphinx source for this tutorial 265 | =============================== 266 | 267 | .. literalinclude:: ipython_directive.rst 268 | -------------------------------------------------------------------------------- /pyplots/ellipses.py: -------------------------------------------------------------------------------- 1 | from pylab import * 2 | from matplotlib.patches import Ellipse 3 | 4 | delta = 45.0 # degrees 5 | 6 | angles = arange(0, 360+delta, delta) 7 | ells = [Ellipse((1, 1), 4, 2, a) for a in angles] 8 | 9 | a = subplot(111, aspect='equal') 10 | 11 | for e in ells: 12 | e.set_clip_box(a.bbox) 13 | e.set_alpha(0.1) 14 | a.add_artist(e) 15 | 16 | xlim(-2, 4) 17 | ylim(-1, 3) 18 | 19 | show() 20 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | # Requirements to build docs 2 | matplotlib 3 | ipython 4 | numpydoc 5 | --------------------------------------------------------------------------------