From d002e9c4e928605e6804e000f4358ee51e564a91 Mon Sep 17 00:00:00 2001 From: Andrey Popp <8mayday@gmail.com> Date: Mon, 19 Jul 2010 13:21:14 +0400 Subject: [PATCH] Added docs. --- .gitignore | 1 + docs/Makefile | 130 +++++++ docs/_static/forkme_right_darkblue_121621.png | Bin 0 -> 7791 bytes docs/_themes/generic/layout.html | 194 +++++++++++ docs/_themes/generic/static/generic.css_t | 221 ++++++++++++ docs/_themes/generic/static/plainwalk.css | 322 ++++++++++++++++++ docs/_themes/generic/static/reset.css | 53 +++ docs/_themes/generic/theme.conf | 4 + docs/conf.py | 220 ++++++++++++ docs/index.rst | 214 ++++++++++++ 10 files changed, 1359 insertions(+) create mode 100644 .gitignore create mode 100644 docs/Makefile create mode 100644 docs/_static/forkme_right_darkblue_121621.png create mode 100644 docs/_themes/generic/layout.html create mode 100644 docs/_themes/generic/static/generic.css_t create mode 100644 docs/_themes/generic/static/plainwalk.css create mode 100644 docs/_themes/generic/static/reset.css create mode 100644 docs/_themes/generic/theme.conf create mode 100644 docs/conf.py create mode 100644 docs/index.rst diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3f0ed21 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +docs/_build/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..b2bf330 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,130 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/generic.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/generic.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/generic" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/generic" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/_static/forkme_right_darkblue_121621.png b/docs/_static/forkme_right_darkblue_121621.png new file mode 100644 index 0000000000000000000000000000000000000000..146ef8a800602169cf78c686fc5a6d138a76bc0a GIT binary patch literal 7791 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 +{%- endblock %} +{%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %} +{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %} +{%- set render_sidebar = (not embedded) and (not theme_nosidebar|tobool) and + (not sidebars == []) %} +{%- set url_root = pathto('', 1) %} +{%- if url_root == '#' %}{% set url_root = '' %}{% endif %} + +{%- macro relbar() %} +
+

{{ _('Navigation') }}

+
    + {%- for rellink in rellinks %} +
  • + {{ rellink[3] }} + {%- if not loop.first %}{{ reldelim2 }}{% endif %}
    • + {%- endfor %} + {%- block rootrellink %} +
  • {{ shorttitle|e }}{{ reldelim1 }}
    • + {%- endblock %} + {%- for parent in parents %} +
  • {{ parent.title }}{{ reldelim1 }}
    • + {%- endfor %} + {%- block relbaritems %} {% endblock %} +
+
+{%- endmacro %} + +{%- macro sidebar() %} + {%- if render_sidebar %} +
+
+ {%- block sidebarlogo %} + {%- if logo %} + + {%- endif %} + {%- endblock %} + {%- if sidebars != None %} + {#- new style sidebar: explicitly include/exclude templates #} + {%- for sidebartemplate in sidebars %} + {%- include sidebartemplate %} + {%- endfor %} + {%- else %} + {#- old style sidebars: using blocks -- should be deprecated #} + {%- block sidebartoc %} + {%- include "localtoc.html" %} + {%- endblock %} + {%- block sidebarrel %} + {%- include "relations.html" %} + {%- endblock %} + {%- block sidebarsourcelink %} + {%- include "sourcelink.html" %} + {%- endblock %} + {%- if customsidebar %} + {%- include customsidebar %} + {%- endif %} + {%- block sidebarsearch %} + {%- include "searchbox.html" %} + {%- endblock %} + {%- endif %} +
+
+ {%- endif %} +{%- endmacro %} + + + + + {{ metatags }} + {%- if not embedded and docstitle %} + {%- set titlesuffix = " — "|safe + docstitle|e %} + {%- else %} + {%- set titlesuffix = "" %} + {%- endif %} + {%- block htmltitle %} + {{ title|striptags }}{{ titlesuffix }} + {%- endblock %} + + + {%- for cssfile in css_files %} + + {%- endfor %} + {%- if not embedded %} + + {%- for scriptfile in script_files %} + + {%- endfor %} + {%- if use_opensearch %} + + {%- endif %} + {%- if favicon %} + + {%- endif %} + {%- endif %} +{%- block linktags %} + {%- if hasdoc('about') %} + + {%- endif %} + {%- if hasdoc('genindex') %} + + {%- endif %} + {%- if hasdoc('search') %} + + {%- endif %} + {%- if hasdoc('copyright') %} + + {%- endif %} + + {%- if parents %} + + {%- endif %} + {%- if next %} + + {%- endif %} + {%- if prev %} + + {%- endif %} +{%- endblock %} +{%- block extrahead %} {% endblock %} + + +{%- block header %}{% endblock %} + +{%- block relbar1 %}{{ relbar() }}{% endblock %} + +{%- block content %} + {%- block sidebar1 %} {# possible location for sidebar #} {% endblock %} + Fork me on GitHub +
+ {%- block document %} +
+ {%- if render_sidebar %} +
+ {%- endif %} +
+ {% block body %} {% endblock %} +
+ {%- if render_sidebar %} +
+ {%- endif %} +
+ {%- endblock %} + + {%- block sidebar2 %}{{ sidebar() }}{% endblock %} +
+
+{%- endblock %} + +{%- block relbar2 %}{{ relbar() }}{% endblock %} + +{%- block footer %} +
+ {%- if show_copyright %} + {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- else %} + {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- endif %} + {%- endif %} + {%- if last_updated %} + {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} + {%- endif %} + {%- if show_sphinx %} + {% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.{% endtrans %} + {%- endif %} +
+{%- endblock %} + + diff --git a/docs/_themes/generic/static/generic.css_t b/docs/_themes/generic/static/generic.css_t new file mode 100644 index 0000000..158b097 --- /dev/null +++ b/docs/_themes/generic/static/generic.css_t @@ -0,0 +1,221 @@ +/* + * nature.css_t + * ~~~~~~~~~~~~ + * + * Sphinx stylesheet -- nature theme. + * + * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); +@import url("reset.css"); +@import url("plainwalk.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: Arial, sans-serif; + font-size: 100%; + background-color: #111; + color: #555; + margin: 0; + padding: 0; +} + +div.documentwrapper { + width: 640px; + margin: 0 auto; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +hr { + border: 1px solid #B1B4B6; +} + +div.document { + background-color: #eee; +} + +div.body { + background-color: #ffffff; + color: #3E4349; + padding: 15px 30px 30px 30px; +} + +div.footer { + color: #555; + width: 100%; + padding: 13px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #444; + text-decoration: underline; +} + +div.related { + background-color: #7D2823; + line-height: 32px; + color: #fff; + text-shadow: 0px 1px 0 #444; + font-size: 0.9em; +} + +div.related a { + color: #fff; +} + +div.sphinxsidebar { + font-size: 0.75em; + line-height: 1.5em; +} + +div.sphinxsidebarwrapper{ + padding: 20px 0; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + font-family: Arial, sans-serif; + color: #222; + font-size: 1.2em; + font-weight: normal; + margin: 0; + padding: 5px 10px; + background-color: #ddd; + text-shadow: 1px 1px 0 white +} + +div.sphinxsidebar h4{ + font-size: 1.1em; +} + +div.sphinxsidebar h3 a { + color: #444; +} + + +div.sphinxsidebar p { + color: #888; + padding: 5px 20px; +} + +div.sphinxsidebar p.topless { +} + +div.sphinxsidebar ul { + margin: 10px 20px; + padding: 0; + color: #000; +} + +div.sphinxsidebar a { + color: #444; +} + +div.sphinxsidebar input { + border: 1px solid #ccc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar input[type=text]{ + margin-left: 20px; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #005B81; + text-decoration: none; +} + +a:hover { + color: #E32E00; + text-decoration: underline; +} + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + line-height: 1.5em; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.highlight{ + background-color: white; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + color: #222; + border: 1px solid #C6C9CB; + margin: 1.5em 0 1.5em 0; + font-size: 90%; + overflow: hidden; +} + +tt { + background-color: #ecf0f3; + color: #222; + /* padding: 1px 2px; */ + font-size: 1.1em; + font-family: monospace; +} + +.viewcode-back { + font-family: Arial, sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} + diff --git a/docs/_themes/generic/static/plainwalk.css b/docs/_themes/generic/static/plainwalk.css new file mode 100644 index 0000000..d6975c3 --- /dev/null +++ b/docs/_themes/generic/static/plainwalk.css @@ -0,0 +1,322 @@ +/* Plainwalk CSS theme v.0.1. + * + * This CSS is suitable for theming content, generated by docutils rst + * processor. If you want to use it, just add `.plainwalk` class to HTML element + * you want to style. Also, this CSS should be used on elements, which was + * reseted with Eric Meyer's reset CSS. + * + * Warning: This theme uses CSS3's `text-shadow` property, not all browsers + * support it. + * + * Copyright (c) 2010, Andrey Popp 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 the Andrey Popp 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 HOLDER 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. + */ + +.plainwalk { + background: #FAFAFA; + font-family: 'Georgia', serif; + font-size: 16px; + color: #444; +} +.plainwalk h1, +.plainwalk h2, +.plainwalk h3, +.plainwalk h4, +.plainwalk h5, +.plainwalk h6, +.plainwalk ul, +.plainwalk ol, +.plainwalk dl, +.plainwalk p, +.plainwalk blockquote { + padding: 7px 0; +} + +.plainwalk h1 a, +.plainwalk h2 a, +.plainwalk h3 a, +.plainwalk h4 a, +.plainwalk h5 a, +.plainwalk h6 a { + text-decoration: none; +} + +.plainwalk img { + padding-bottom: 0px; +} +.plainwalk h1, +.plainwalk h2, +.plainwalk h3, +.plainwalk h4, +.plainwalk h5, +.plainwalk h6 { + font-weight: normal; +} +.plainwalk p, +.plainwalk li { + line-height: 1.45em; +} +/* elements */ +.plainwalk table { + margin: 10px 0; +} +.plainwalk dt { + font-style: italic; + font-weight: bold; + margin-bottom: 1px; +} +.plainwalk dd { + margin-left: 20px; + margin-bottom: 10px; +} +.plainwalk tt { + font-size: 90%; + white-space: nowrap; + padding: 0 3px; +} +.plainwalk tt, +.plainwalk pre { + font-family: Consolas, Monaco, Menlo, 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace !important; + background: #F1F1F1; +} +.plainwalk pre { + font-size: 85%; + line-height: 120%; + display: block; + padding: 10px; +} +.plainwalk img { + display: block; +} +.plainwalk em { + font-style: italic; +} +.plainwalk strong { + font-weight: bold; +} +.plainwalk hr{ + border: 1px solid #F1F1F1; + border-width: 0 0 1px 0; + margin: 10px 10px 10px 10px; +} +/* headings */ +.plainwalk h1 { + font-size: 196%; + font-style: normal; + color:#7D2823; +} +.plainwalk h2 { + font-size: 167%; + font-style: normal; + color:#7D2823; +} +.plainwalk h3 { + font-size:146.5%; + font-style: normal; + color:#A2332C; +} +.plainwalk h4 { + font-size: 123.1%; + font-style: normal; + color: #A2332C; +} +.plainwalk h5 { + font-size: 108%; + font-style: italic; + color:#A2332C; +} +.plainwalk h6 { + font-size: 108%; + font-style: italic; + color:#000000; +} +/* links */ +.plainwalk a { + color: #7D2823; + text-decoration: underline; +} +.plainwalk a:focus, +.plainwalk a:hover { + color:#A2332C; + text-decoration: underline; +} +.plainwalk a:visited { + color:#1F1F1F; +} +.plainwalk h1 a { + color:#7D2823; +} +.plainwalk h2 a { + color:#7D2823; +} +.plainwalk h3 a { + color:#A2332C; +} +.plainwalk h4 a { + color: #A2332C; +} +.plainwalk h5 a { + color: #A2332C; +} +.plainwalk h6 a { + color: #000; +} +.plainwalk h1 a:visited { + color:#7D2823; +} +.plainwalk h2 a:visited { + color:#7D2823; +} +.plainwalk h3 a:visited { + color:#A2332C; +} +.plainwalk h4 a:visited { + color: #A2332C; +} +.plainwalk h5 a:visited { + color: #A2332C; +} +.plainwalk h6 a:visited { + color: #000; +} +/* numbered list */ +.plainwalk ol li { + list-style-type: decimal; + margin-left: 40px; +} +.plainwalk ol.upperalpha li { + list-style-type: upper-latin; +} +.plainwalk ol.loweralpha li { + list-style-type: lower-latin; +} +.plainwalk ol.upperroman li { + list-style-type: upper-roman; +} +.plainwalk ol.lowerroman li { + list-style-type: lower-roman; +} +/* standard list */ +.plainwalk ul li { + list-style-type: square; + margin-left:40px; + margin-bottom: 3px; +} +/* quotes */ +.plainwalk blockquote { + color: #AAA; + font-size: 95%; + font-style: italic; + border-left: 2px solid #EEE; + padding-left: 10px; +} +/* sidebar */ +.plainwalk .sidebar { + float: right; + width: 40%; + padding: 10px; + margin: 5px; + background: #F1F1F1; + font-size: 90%; +} +.plainwalk .sidebar-title { + font-size:110%; + font-weight:normal; + font-style: italic; + color:#A2332C; + padding: 0; +} +.plainwalk .sidebar .last { + padding: 0; +} +/* admonition */ +.plainwalk .admonition, +.plainwalk .note, +.plainwalk .attention, +.plainwalk .caution, +.plainwalk .danger, +.plainwalk .error, +.plainwalk .hint, +.plainwalk .important, +.plainwalk .tip, +.plainwalk .warning +{ + margin: 10px 0; + padding: 10px; + background: #F1F1F1; + font-size: 90%; +} +.plainwalk .admonition-title { + font-size:110%; + margin-right: 5px; + display: inline; + color:#A2332C; + padding: 0; +} +.plainwalk .admonition .last, +.plainwalk .note .last, +.plainwalk .caution .last, +.plainwalk .attention .last, +.plainwalk .danger .last, +.plainwalk .error .last, +.plainwalk .hint .last, +.plainwalk .important .last, +.plainwalk .tip .last, +.plainwalk .warning .last { display: inline; } +/* footnote */ +.plainwalk a.fn-backref, +.plainwalk a.footnote-reference { + text-decoration: none; +} +.plainwalk table.footnote td { + font-size: 95%; + padding: 5px; +} +/* plainwalks */ +.plainwalk .plainwalks .topic-title { + font-size:110%; + color:#A2332C; + margin:0; + padding-bottom:0; +} +/* docinfo */ +.plainwalk table.docinfo { + font-size: 90%; +} +.plainwalk table.docinfo td, +.plainwalk table.docinfo th { + padding: 2px; +} +.plainwalk table.docinfo th { + text-align: right; +} +/* css3 fancies */ +.plainwalk.css3 h1, +.plainwalk.css3 h2, +.plainwalk.css3 h3, +.plainwalk.css3 h4, +.plainwalk.css3 h5, +.plainwalk.css3 h6 +{ text-shadow: 1px 1px 0px #EEE; } +.plainwalk.css3 pre { text-shadow:none; } diff --git a/docs/_themes/generic/static/reset.css b/docs/_themes/generic/static/reset.css new file mode 100644 index 0000000..1c85489 --- /dev/null +++ b/docs/_themes/generic/static/reset.css @@ -0,0 +1,53 @@ +/* http://meyerweb.com/eric/tools/css/reset/ */ +/* v1.0 | 20080212 */ + +html, body, div, span, applet, object, iframe, +h1, h2, h3, h4, h5, h6, p, blockquote, pre, +a, abbr, acronym, address, big, cite, code, +del, dfn, em, font, img, ins, kbd, q, s, samp, +small, strike, strong, sub, sup, tt, var, +b, u, i, center, +dl, dt, dd, ol, ul, li, +fieldset, form, label, legend, +table, caption, tbody, tfoot, thead, tr, th, td { + margin: 0; + padding: 0; + border: 0; + outline: 0; + font-size: 100%; + vertical-align: baseline; + background: transparent; +} +body { + line-height: 1; +} +ol, ul { + list-style: none; +} +blockquote, q { + quotes: none; +} +blockquote:before, blockquote:after, +q:before, q:after { + content: ''; + content: none; +} + +/* remember to define focus styles! */ +:focus { + outline: 0; +} + +/* remember to highlight inserts somehow! */ +ins { + text-decoration: none; +} +del { + text-decoration: line-through; +} + +/* tables still need 'cellspacing="0"' in the markup */ +table { + border-collapse: collapse; + border-spacing: 0; +} diff --git a/docs/_themes/generic/theme.conf b/docs/_themes/generic/theme.conf new file mode 100644 index 0000000..8c36b82 --- /dev/null +++ b/docs/_themes/generic/theme.conf @@ -0,0 +1,4 @@ +[theme] +inherit = basic +stylesheet = generic.css +pygments_style = tango diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..66872c9 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,220 @@ +# -*- coding: utf-8 -*- +# +# generic documentation build configuration file, created by +# sphinx-quickstart on Mon Jul 19 01:35:17 2010. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.append(os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'generic' +copyright = u'2010, Andrey Popp' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.2' +# The full version, including alpha/beta/rc tags. +release = '0.2' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'generic' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = {"nosidebar": True} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ["./_themes"] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'genericdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'generic.tex', u'generic Documentation', + u'Andrey Popp', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'generic', u'generic Documentation', + [u'Andrey Popp'], 1) +] + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..f9b0865 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,214 @@ +.. generic documentation master file, created by + sphinx-quickstart on Mon Jul 19 01:35:17 2010. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Generic documentation +================================ + +.. toctree:: + :maxdepth: 2 + +Generic is a programming library for Python that provides tools for generic +programming. By, now there is only one feature -- multiple dispatch. + +Multiple dispatch +----------------- + +Multiple dispatch (or multidispatch) is a technique of choosing the function +implementation at runtime based on its argument types. For illustrating the +problem, let's see example function that behaves differently when you provide +it ``str`` or ``int`` object as argument:: + + def add_two(x): + if isinstance(x, int): + return add_two_int(x) + elif isinstance(x, str): + return add_two_str(x) + else: + raise TypeError("Wrong argument type.") + + def add_two_int(x): + return x + 2 + + def add_two_str(x): + return x + "2" + + assert add_two(2) == 4 + assert add_two("2") == "22" + +The last two assertions are true -- the function ``add_two`` dispatches their +execution either to ``add_two_int`` or ``add_two_str`` depending on its +argument type. As for me, this piece of code is very verbose and unpythonic. +This is there ``generic.multidispatch`` comes in place. + + +Declaring multifunctions +~~~~~~~~~~~~~~~~~~~~~~~~ + +With help of ``generic.multidispatch`` module we can rewrite the latter +piece of code like that:: + + from generic.multidispatch import multifunction + + @multifunction(int) + def add_two(x): + return x + 2 + + @add_two.when(str) + def add_two(x): + return x + "2" + + assert add_two(2) == 4 + assert add_two("2") == "22" + +And again -- assertions are fulfilled, but now code is more readable and +declarative. + +Furthermore, this way of writing functions is more extensible, because we can +add another branch (another implementation for some other argument type) to our +function ``add_two`` by being able not to modify original declarations, even if +they are defined in another module or package:: + + from mymodule import add_two + + @add_two.when(list) + def add_two(x): + return x + [2] + +Doing the same thing for function from first example would require modify +function code for each type we want to handle, which isn't good. + + +Overriding multifunction implementations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you're trying to define multifunction implementation for types, that already have another implementation, then ``TypeError`` exception would be raised. But there is a way to do this kind of things in explicitly manner:: + + @add_two.override(list) + def add_two(x): + return x + [2, 2] + +Note the using of the ``@add_two.override`` decorator instead of the +``@add_two.when`` one. + + +Multifunctions with more than one arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The example from the previous section demonstrates basic usage of +``generic.multidispatch`` for defining multifunctions with single argument. +Now, let's see how we can define multifunctions with more than one arguments:: + + @multifunction(int, int) + def add(x, y): + return x + y + + @add.when(str, str) + def add(x, y): + return add(int(x), int(y)) + +This is as simple as it can be -- just pass more types to ``multifunction`` +decorator to produce multifunction that dispatches by exactly that number of +arguments. + +If function takes more arguments than the number of types you have passed to +``multifunction`` decorator, they will be treated as typical arguments and +there will be no dispatching by them. The same holds for keyword and variable +(prefixed with ``*`` or ``**``) arguments. + +The only requirements for declaring multifunctions are: + +* The number of function's positional arguments should not be less than the + number of types passed to ``multifunction`` decorator. This is because + dispatching is allowed only by positional arguments. + +* All function implementations that are related to one multifunction should + have the same arity for positional arguments. + + +Declaring multimethods +~~~~~~~~~~~~~~~~~~~~~~ + +*Generic* can help with defining multifunctions, but what about methods? There +are another decorators for them:: + + from generic.multidispatch import multimethod + from generic.multidispatch import has_multimethods + + @has_multimethods + class A(object): + + @multimethod(int) + def foo(self, x): + return x + 1 + + @foo.when(str) + def foo(self, x): + return x + "1" + + assert A().foo(1) == 2 + assert A().foo("1") == "11" + +It may seen works exactly like multifunctions, but it's not. The main +difference between multifunctions and multimethods is that the latter is +dispatched also by its class type. This is why we need another decorator +``has_multimethods`` for classes that define multimethods. + +.. warning:: + Decorating class with ``has_multimethods`` decorator is mandatory to + multimethods declaration to work. This is because we cannot know method's + class at the time of method declaration. + +Let's see example demonstrates usage of that feature:: + + @has_multimethods + class B(A): + + @A.foo.when(list) + def foo(self, x): + return x + [1] + + assert B().foo(1) == 2 + assert B().foo("1") == "11" + assert B().foo([1]) == [1, 1] + +As you can see, we have extended method ``foo`` inherits all previous +declarations, but also adds another one -- for ``list`` type. Note, that declaration is only works for ``B`` objects, but not for ``A`` ones:: + + A().foo([1]) # bad! raises TypeError + + +Also, note, that all multimethods declarations are overridden implicitly, so +the ``A.foo.override`` and ``A.foo.when`` decorators are the same. + +All other things that are true for multifunctions are also hold for +multimethods. + +Development +----------- + +Development of *generic* library takes place at `github +`_ -- there are code repository and issue +tracker. + +API referrence +-------------- + +.. autofunction:: generic.multidispatch.multifunction + +.. autofunction:: generic.multidispatch.multimethod + +.. autofunction:: generic.multidispatch.has_multimethods + +.. autoclass:: generic.multidispatch.FunctionDispatcher + +.. autoclass:: generic.multidispatch.MethodDispatcher + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` +