From 7f4d38076146409561651c9321ca7534db25a2ad Mon Sep 17 00:00:00 2001 From: Brian Muller Date: Mon, 5 Jan 2015 10:32:24 -0500 Subject: [PATCH] added start to sphinx docs --- .gitignore | 3 +- docs/Makefile | 177 ++++++ docs/_themes/armstrong/LICENSE | 26 + docs/_themes/armstrong/layout.html | 48 ++ docs/_themes/armstrong/rtd-themes.conf | 65 ++ docs/_themes/armstrong/static/rtd.css_t | 781 ++++++++++++++++++++++++ docs/_themes/armstrong/theme.conf | 65 ++ docs/conf.py | 267 ++++++++ docs/index.rst | 21 + docs/intro.rst | 4 + docs/source/kademlia.rst | 85 +++ docs/source/kademlia.tests.rst | 38 ++ docs/source/modules.rst | 7 + kademlia/network.py | 6 +- setup.py | 2 +- 15 files changed, 1590 insertions(+), 5 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/_themes/armstrong/LICENSE create mode 100644 docs/_themes/armstrong/layout.html create mode 100644 docs/_themes/armstrong/rtd-themes.conf create mode 100644 docs/_themes/armstrong/static/rtd.css_t create mode 100644 docs/_themes/armstrong/theme.conf create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/intro.rst create mode 100644 docs/source/kademlia.rst create mode 100644 docs/source/kademlia.tests.rst create mode 100644 docs/source/modules.rst diff --git a/.gitignore b/.gitignore index cad8e67..a518055 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,5 @@ apidoc *.pyc build dist -kademlia.egg-info \ No newline at end of file +kademlia.egg-info +docs/_build \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..b99f888 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +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 " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @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/Kademlia.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Kademlia.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/Kademlia" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Kademlia" + @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." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @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." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +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." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/_themes/armstrong/LICENSE b/docs/_themes/armstrong/LICENSE new file mode 100644 index 0000000..894aa01 --- /dev/null +++ b/docs/_themes/armstrong/LICENSE @@ -0,0 +1,26 @@ +Copyright (c) 2011 Bay Citizen & Texas Tribune + +Original ReadTheDocs.org code +Copyright (c) 2010 Charles Leifer, Eric Holscher, Bobby Grace + +Permission is hereby granted, free of charge, to any person +obtaining a copy of this software and associated documentation +files (the "Software"), to deal in the Software without +restriction, including without limitation the rights to use, +copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + diff --git a/docs/_themes/armstrong/layout.html b/docs/_themes/armstrong/layout.html new file mode 100644 index 0000000..d7b8fbb --- /dev/null +++ b/docs/_themes/armstrong/layout.html @@ -0,0 +1,48 @@ +{% extends "basic/layout.html" %} + +{% set script_files = script_files + [pathto("_static/searchtools.js", 1)] %} + +{% block htmltitle %} +{{ super() }} + + + +{% 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 %} +{%- if theme_show_rtd %} + {% trans %}
Theme based on Read The Docs{% endtrans %} +{% endif %} +
+ + +{% if theme_analytics_code %} + + +{% endif %} + +{% endblock %} diff --git a/docs/_themes/armstrong/rtd-themes.conf b/docs/_themes/armstrong/rtd-themes.conf new file mode 100644 index 0000000..5930488 --- /dev/null +++ b/docs/_themes/armstrong/rtd-themes.conf @@ -0,0 +1,65 @@ +[theme] +inherit = default +stylesheet = rtd.css +pygment_style = default +show_sphinx = False + +[options] +show_rtd = True + +white = #ffffff +almost_white = #f8f8f8 +barely_white = #f2f2f2 +dirty_white = #eeeeee +almost_dirty_white = #e6e6e6 +dirtier_white = #dddddd +lighter_gray = #cccccc +gray_a = #aaaaaa +gray_9 = #999999 +light_gray = #888888 +gray_7 = #777777 +gray = #666666 +dark_gray = #444444 +gray_2 = #222222 +black = #111111 +light_color = #e8ecef +light_medium_color = #DDEAF0 +medium_color = #8ca1af +medium_color_link = #86989b +medium_color_link_hover = #a6b8bb +dark_color = #465158 + +h1 = #000000 +h2 = #465158 +h3 = #6c818f + +link_color = #444444 +link_color_decoration = #CCCCCC + +medium_color_hover = #697983 +green_highlight = #8ecc4c + + +positive_dark = #609060 +positive_medium = #70a070 +positive_light = #e9ffe9 + +negative_dark = #900000 +negative_medium = #b04040 +negative_light = #ffe9e9 +negative_text = #c60f0f + +ruler = #abc + +viewcode_bg = #f4debf +viewcode_border = #ac9 + +highlight = #ffe080 + +code_background = #eeeeee + +background = #465158 +background_link = #ffffff +background_link_half = #ffffff +background_text = #eeeeee +background_text_link = #86989b diff --git a/docs/_themes/armstrong/static/rtd.css_t b/docs/_themes/armstrong/static/rtd.css_t new file mode 100644 index 0000000..90354c3 --- /dev/null +++ b/docs/_themes/armstrong/static/rtd.css_t @@ -0,0 +1,781 @@ +/* + * rtd.css + * ~~~~~~~~~~~~~~~ + * + * Sphinx stylesheet -- sphinxdoc theme. Originally created by + * Armin Ronacher for Werkzeug. + * + * Customized for ReadTheDocs by Eric Pierce & Eric Holscher + * + * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* RTD colors + * light blue: {{ theme_light_color }} + * medium blue: {{ theme_medium_color }} + * dark blue: {{ theme_dark_color }} + * dark grey: {{ theme_grey_color }} + * + * medium blue hover: {{ theme_medium_color_hover }}; + * green highlight: {{ theme_green_highlight }} + * light blue (project bar): {{ theme_light_color }} + */ + +@import url("basic.css"); + +/* PAGE LAYOUT -------------------------------------------------------------- */ + +body { + font: 100%/1.5 "ff-meta-web-pro-1","ff-meta-web-pro-2",Arial,"Helvetica Neue",sans-serif; + text-align: center; + color: black; + background-color: {{ theme_background }}; + padding: 0; + margin: 0; +} + +div.document { + text-align: left; + background-color: {{ theme_light_color }}; +} + +div.bodywrapper { + background-color: {{ theme_white }}; + border-left: 1px solid {{ theme_lighter_gray }}; + border-bottom: 1px solid {{ theme_lighter_gray }}; + margin: 0 0 0 16em; +} + +div.body { + margin: 0; + padding: 0.5em 1.3em; + max-width: 55em; + min-width: 20em; +} + +div.related { + font-size: 1em; + background-color: {{ theme_background }}; +} + +div.documentwrapper { + float: left; + width: 100%; + background-color: {{ theme_light_color }}; +} + + +/* HEADINGS --------------------------------------------------------------- */ + +h1 { + margin: 0; + padding: 0.7em 0 0.3em 0; + font-size: 1.5em; + line-height: 1.15; + color: {{ theme_h1 }}; + clear: both; +} + +h2 { + margin: 2em 0 0.2em 0; + font-size: 1.35em; + padding: 0; + color: {{ theme_h2 }}; +} + +h3 { + margin: 1em 0 -0.3em 0; + font-size: 1.2em; + color: {{ theme_h3 }}; +} + +div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a { + color: black; +} + +h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor { + display: none; + margin: 0 0 0 0.3em; + padding: 0 0.2em 0 0.2em; + color: {{ theme_gray_a }} !important; +} + +h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, +h5:hover a.anchor, h6:hover a.anchor { + display: inline; +} + +h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover, +h5 a.anchor:hover, h6 a.anchor:hover { + color: {{ theme_gray_7 }}; + background-color: {{ theme_dirty_white }}; +} + + +/* LINKS ------------------------------------------------------------------ */ + +/* Normal links get a pseudo-underline */ +a { + color: {{ theme_link_color }}; + text-decoration: none; + border-bottom: 1px solid {{ theme_link_color_decoration }}; +} + +/* Links in sidebar, TOC, index trees and tables have no underline */ +.sphinxsidebar a, +.toctree-wrapper a, +.indextable a, +#indices-and-tables a { + color: {{ theme_dark_gray }}; + text-decoration: none; + border-bottom: none; +} + +/* Most links get an underline-effect when hovered */ +a:hover, +div.toctree-wrapper a:hover, +.indextable a:hover, +#indices-and-tables a:hover { + color: {{ theme_black }}; + text-decoration: none; + border-bottom: 1px solid {{ theme_black }}; +} + +/* Footer links */ +div.footer a { + color: {{ theme_background_text_link }}; + text-decoration: none; + border: none; +} +div.footer a:hover { + color: {{ theme_medium_color_link_hover }}; + text-decoration: underline; + border: none; +} + +/* Permalink anchor (subtle grey with a red hover) */ +div.body a.headerlink { + color: {{ theme_lighter_gray }}; + font-size: 1em; + margin-left: 6px; + padding: 0 4px 0 4px; + text-decoration: none; + border: none; +} +div.body a.headerlink:hover { + color: {{ theme_negative_text }}; + border: none; +} + + +/* NAVIGATION BAR --------------------------------------------------------- */ + +div.related ul { + height: 2.5em; +} + +div.related ul li { + margin: 0; + padding: 0.65em 0; + float: left; + display: block; + color: {{ theme_background_link_half }}; /* For the >> separators */ + font-size: 0.8em; +} + +div.related ul li.right { + float: right; + margin-right: 5px; + color: transparent; /* Hide the | separators */ +} + +/* "Breadcrumb" links in nav bar */ +div.related ul li a { + order: none; + background-color: inherit; + font-weight: bold; + margin: 6px 0 6px 4px; + line-height: 1.75em; + color: {{ theme_background_link }}; + text-shadow: 0 1px rgba(0, 0, 0, 0.5); + padding: 0.4em 0.8em; + border: none; + border-radius: 3px; +} +/* previous / next / modules / index links look more like buttons */ +div.related ul li.right a { + margin: 0.375em 0; + background-color: {{ theme_medium_color_hover }}; + text-shadow: 0 1px rgba(0, 0, 0, 0.5); + border-radius: 3px; + -webkit-border-radius: 3px; + -moz-border-radius: 3px; +} +/* All navbar links light up as buttons when hovered */ +div.related ul li a:hover { + background-color: {{ theme_medium_color }}; + color: {{ theme_white }}; + text-decoration: none; + border-radius: 3px; + -webkit-border-radius: 3px; + -moz-border-radius: 3px; +} +/* Take extra precautions for tt within links */ +a tt, +div.related ul li a tt { + background: inherit !important; + color: inherit !important; +} + + +/* SIDEBAR ---------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 0; +} + +div.sphinxsidebar { + margin: 0; + margin-left: -100%; + float: left; + top: 3em; + left: 0; + padding: 0 1em; + width: 14em; + font-size: 1em; + text-align: left; + background-color: {{ theme_light_color }}; +} + +div.sphinxsidebar img { + max-width: 12em; +} + +div.sphinxsidebar h3, div.sphinxsidebar h4 { + margin: 1.2em 0 0.3em 0; + font-size: 1em; + padding: 0; + color: {{ theme_gray_2 }}; + font-family: "ff-meta-web-pro-1", "ff-meta-web-pro-2", "Arial", "Helvetica Neue", sans-serif; +} + +div.sphinxsidebar h3 a { + color: {{ theme_grey_color }}; +} + +div.sphinxsidebar ul, +div.sphinxsidebar p { + margin-top: 0; + padding-left: 0; + line-height: 130%; + background-color: {{ theme_light_color }}; +} + +/* No bullets for nested lists, but a little extra indentation */ +div.sphinxsidebar ul ul { + list-style-type: none; + margin-left: 1.5em; + padding: 0; +} + +/* A little top/bottom padding to prevent adjacent links' borders + * from overlapping each other */ +div.sphinxsidebar ul li { + padding: 1px 0; +} + +/* A little left-padding to make these align with the ULs */ +div.sphinxsidebar p.topless { + padding-left: 0 0 0 1em; +} + +/* Make these into hidden one-liners */ +div.sphinxsidebar ul li, +div.sphinxsidebar p.topless { + white-space: nowrap; + overflow: hidden; +} +/* ...which become visible when hovered */ +div.sphinxsidebar ul li:hover, +div.sphinxsidebar p.topless:hover { + overflow: visible; +} + +/* Search text box and "Go" button */ +#searchbox { + margin-top: 2em; + margin-bottom: 1em; + background: {{ theme_dirtier_white }}; + padding: 0.5em; + border-radius: 6px; + -moz-border-radius: 6px; + -webkit-border-radius: 6px; +} +#searchbox h3 { + margin-top: 0; +} + +/* Make search box and button abut and have a border */ +input, +div.sphinxsidebar input { + border: 1px solid {{ theme_gray_9 }}; + float: left; +} + +/* Search textbox */ +input[type="text"] { + margin: 0; + padding: 0 3px; + height: 20px; + width: 144px; + border-top-left-radius: 3px; + border-bottom-left-radius: 3px; + -moz-border-radius-topleft: 3px; + -moz-border-radius-bottomleft: 3px; + -webkit-border-top-left-radius: 3px; + -webkit-border-bottom-left-radius: 3px; +} +/* Search button */ +input[type="submit"] { + margin: 0 0 0 -1px; /* -1px prevents a double-border with textbox */ + height: 22px; + color: {{ theme_dark_gray }}; + background-color: {{ theme_light_color }}; + padding: 1px 4px; + font-weight: bold; + border-top-right-radius: 3px; + border-bottom-right-radius: 3px; + -moz-border-radius-topright: 3px; + -moz-border-radius-bottomright: 3px; + -webkit-border-top-right-radius: 3px; + -webkit-border-bottom-right-radius: 3px; +} +input[type="submit"]:hover { + color: {{ theme_white }}; + background-color: {{ theme_green_highlight }}; +} + +div.sphinxsidebar p.searchtip { + clear: both; + padding: 0.5em 0 0 0; + background: {{ theme_dirtier_white }}; + color: {{ theme_gray }}; + font-size: 0.9em; +} + +/* Sidebar links are unusual */ +div.sphinxsidebar li a, +div.sphinxsidebar p a { + background: {{ theme_light_color }}; /* In case links overlap main content */ + border-radius: 3px; + -moz-border-radius: 3px; + -webkit-border-radius: 3px; + border: 1px solid transparent; /* To prevent things jumping around on hover */ + padding: 0 5px 0 5px; +} +div.sphinxsidebar li a:hover, +div.sphinxsidebar p a:hover { + color: {{ theme_black }}; + text-decoration: none; + border: 1px solid {{ theme_light_gray }}; +} + +/* Tweak any link appearing in a heading */ +div.sphinxsidebar h3 a { +} + + + + +/* OTHER STUFF ------------------------------------------------------------ */ + +cite, code, tt { + font-family: 'Consolas', 'Deja Vu Sans Mono', + 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; + letter-spacing: 0.01em; +} + +tt { + background-color: {{ theme_code_background }}; + color: {{ theme_dark_gray }}; +} + +tt.descname, tt.descclassname, tt.xref { + border: 0; +} + +hr { + border: 1px solid {{ theme_ruler }}; + margin: 2em; +} + +pre, #_fontwidthtest { + font-family: 'Consolas', 'Deja Vu Sans Mono', + 'Bitstream Vera Sans Mono', monospace; + margin: 1em 2em; + font-size: 0.95em; + letter-spacing: 0.015em; + line-height: 120%; + padding: 0.5em; + border: 1px solid {{ theme_lighter_gray }}; + background-color: {{ theme_code_background }}; + border-radius: 6px; + -moz-border-radius: 6px; + -webkit-border-radius: 6px; +} + +pre a { + color: inherit; + text-decoration: underline; +} + +td.linenos pre { + padding: 0.5em 0; +} + +div.quotebar { + background-color: {{ theme_almost_white }}; + max-width: 250px; + float: right; + padding: 2px 7px; + border: 1px solid {{ theme_lighter_gray }}; +} + +div.topic { + background-color: {{ theme_almost_white }}; +} + +table { + border-collapse: collapse; + margin: 0 -0.5em 0 -0.5em; +} + +table td, table th { + padding: 0.2em 0.5em 0.2em 0.5em; +} + + +/* ADMONITIONS AND WARNINGS ------------------------------------------------- */ + +/* Shared by admonitions, warnings and sidebars */ +div.admonition, +div.warning, +div.sidebar { + font-size: 0.9em; + margin: 2em; + padding: 0; + /* + border-radius: 6px; + -moz-border-radius: 6px; + -webkit-border-radius: 6px; + */ +} +div.admonition p, +div.warning p, +div.sidebar p { + margin: 0.5em 1em 0.5em 1em; + padding: 0; +} +div.admonition pre, +div.warning pre, +div.sidebar pre { + margin: 0.4em 1em 0.4em 1em; +} +div.admonition p.admonition-title, +div.warning p.admonition-title, +div.sidebar p.sidebar-title { + margin: 0; + padding: 0.1em 0 0.1em 0.5em; + color: white; + font-weight: bold; + font-size: 1.1em; + text-shadow: 0 1px rgba(0, 0, 0, 0.5); +} +div.admonition ul, div.admonition ol, +div.warning ul, div.warning ol, +div.sidebar ul, div.sidebar ol { + margin: 0.1em 0.5em 0.5em 3em; + padding: 0; +} + + +/* Admonitions and sidebars only */ +div.admonition, div.sidebar { + border: 1px solid {{ theme_positive_dark }}; + background-color: {{ theme_positive_light }}; +} +div.admonition p.admonition-title, +div.sidebar p.sidebar-title { + background-color: {{ theme_positive_medium }}; + border-bottom: 1px solid {{ theme_positive_dark }}; +} + + +/* Warnings only */ +div.warning { + border: 1px solid {{ theme_negative_dark }}; + background-color: {{ theme_negative_light }}; +} +div.warning p.admonition-title { + background-color: {{ theme_negative_medium }}; + border-bottom: 1px solid {{ theme_negative_dark }}; +} + + +/* Sidebars only */ +div.sidebar { + max-width: 200px; +} + + + +div.versioninfo { + margin: 1em 0 0 0; + border: 1px solid {{ theme_lighter_gray }}; + background-color: {{ theme_light_medium_color }}; + padding: 8px; + line-height: 1.3em; + font-size: 0.9em; +} + +.viewcode-back { + font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', + 'Verdana', sans-serif; +} + +div.viewcode-block:target { + background-color: {{ theme_viewcode_bg }}; + border-top: 1px solid {{ theme_viewcode_border }}; + border-bottom: 1px solid {{ theme_viewcode_border }}; +} + +dl { + margin: 1em 0 2.5em 0; +} + +/* Highlight target when you click an internal link */ +dt:target { + background: {{ theme_highlight }}; +} +/* Don't highlight whole divs */ +div.highlight { + background: transparent; +} +/* But do highlight spans (so search results can be highlighted) */ +span.highlight { + background: {{ theme_highlight }}; +} + +div.footer { + background-color: {{ theme_background }}; + color: {{ theme_background_text }}; + padding: 0 2em 2em 2em; + clear: both; + font-size: 0.8em; + text-align: center; +} + +p { + margin: 0.8em 0 0.5em 0; +} + +.section p img { + margin: 1em 2em; +} + + +/* MOBILE LAYOUT -------------------------------------------------------------- */ + +@media screen and (max-width: 600px) { + + h1, h2, h3, h4, h5 { + position: relative; + } + + ul { + padding-left: 1.75em; + } + + div.bodywrapper a.headerlink, #indices-and-tables h1 a { + color: {{ theme_almost_dirty_white }}; + font-size: 80%; + float: right; + line-height: 1.8; + position: absolute; + right: -0.7em; + visibility: inherit; + } + + div.bodywrapper h1 a.headerlink, #indices-and-tables h1 a { + line-height: 1.5; + } + + pre { + font-size: 0.7em; + overflow: auto; + word-wrap: break-word; + white-space: pre-wrap; + } + + div.related ul { + height: 2.5em; + padding: 0; + text-align: left; + } + + div.related ul li { + clear: both; + color: {{ theme_dark_color }}; + padding: 0.2em 0; + } + + div.related ul li:last-child { + border-bottom: 1px dotted {{ theme_medium_color }}; + padding-bottom: 0.4em; + margin-bottom: 1em; + width: 100%; + } + + div.related ul li a { + color: {{ theme_dark_color }}; + padding-right: 0; + } + + div.related ul li a:hover { + background: inherit; + color: inherit; + } + + div.related ul li.right { + clear: none; + padding: 0.65em 0; + margin-bottom: 0.5em; + } + + div.related ul li.right a { + color: {{ theme_white }}; + padding-right: 0.8em; + } + + div.related ul li.right a:hover { + background-color: {{ theme_medium_color }}; + } + + div.body { + clear: both; + min-width: 0; + word-wrap: break-word; + } + + div.bodywrapper { + margin: 0 0 0 0; + } + + div.sphinxsidebar { + float: none; + margin: 0; + width: auto; + } + + div.sphinxsidebar input[type="text"] { + height: 2em; + line-height: 2em; + width: 70%; + } + + div.sphinxsidebar input[type="submit"] { + height: 2em; + margin-left: 0.5em; + width: 20%; + } + + div.sphinxsidebar p.searchtip { + background: inherit; + margin-bottom: 1em; + } + + div.sphinxsidebar ul li, div.sphinxsidebar p.topless { + white-space: normal; + } + + .bodywrapper img { + display: block; + margin-left: auto; + margin-right: auto; + max-width: 100%; + } + + div.documentwrapper { + float: none; + } + + div.admonition, div.warning, pre, blockquote { + margin-left: 0em; + margin-right: 0em; + } + + .body p img { + margin: 0; + } + + #searchbox { + background: transparent; + } + + .related:not(:first-child) li { + display: none; + } + + .related:not(:first-child) li.right { + display: block; + } + + div.footer { + padding: 1em; + } + + .rtd_doc_footer .badge { + float: none; + margin: 1em auto; + position: static; + } + + .rtd_doc_footer .badge.revsys-inline { + margin-right: auto; + margin-bottom: 2em; + } + + table.indextable { + display: block; + width: auto; + } + + .indextable tr { + display: block; + } + + .indextable td { + display: block; + padding: 0; + width: auto !important; + } + + .indextable td dt { + margin: 1em 0; + } + + ul.search { + margin-left: 0.25em; + } + + ul.search li div.context { + font-size: 90%; + line-height: 1.1; + margin-bottom: 1; + margin-left: 0; + } + +} diff --git a/docs/_themes/armstrong/theme.conf b/docs/_themes/armstrong/theme.conf new file mode 100644 index 0000000..5930488 --- /dev/null +++ b/docs/_themes/armstrong/theme.conf @@ -0,0 +1,65 @@ +[theme] +inherit = default +stylesheet = rtd.css +pygment_style = default +show_sphinx = False + +[options] +show_rtd = True + +white = #ffffff +almost_white = #f8f8f8 +barely_white = #f2f2f2 +dirty_white = #eeeeee +almost_dirty_white = #e6e6e6 +dirtier_white = #dddddd +lighter_gray = #cccccc +gray_a = #aaaaaa +gray_9 = #999999 +light_gray = #888888 +gray_7 = #777777 +gray = #666666 +dark_gray = #444444 +gray_2 = #222222 +black = #111111 +light_color = #e8ecef +light_medium_color = #DDEAF0 +medium_color = #8ca1af +medium_color_link = #86989b +medium_color_link_hover = #a6b8bb +dark_color = #465158 + +h1 = #000000 +h2 = #465158 +h3 = #6c818f + +link_color = #444444 +link_color_decoration = #CCCCCC + +medium_color_hover = #697983 +green_highlight = #8ecc4c + + +positive_dark = #609060 +positive_medium = #70a070 +positive_light = #e9ffe9 + +negative_dark = #900000 +negative_medium = #b04040 +negative_light = #ffe9e9 +negative_text = #c60f0f + +ruler = #abc + +viewcode_bg = #f4debf +viewcode_border = #ac9 + +highlight = #ffe080 + +code_background = #eeeeee + +background = #465158 +background_link = #ffffff +background_link_half = #ffffff +background_text = #eeeeee +background_text_link = #86989b diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..74653c9 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,267 @@ +# -*- coding: utf-8 -*- +# +# Kademlia documentation build configuration file, created by +# sphinx-quickstart on Mon Jan 5 09:42:46 2015. +# +# 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 +import 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.insert(0, 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.todo', + 'sphinx.ext.viewcode', + 'sphinxcontrib.napoleon' +] + +# 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'Kademlia' +copyright = u'2015, Brian Muller' + +# 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. +sys.path.insert(0, os.path.abspath('..')) +import kademlia +version = kademlia.version +# The full version, including alpha/beta/rc tags. +release = version + +# 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 = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- 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 = "armstrong" + +# 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 = { 'stickysidebar': 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'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# 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 = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Kademliadoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'Kademlia.tex', u'Kademlia Documentation', + u'Brian Muller', '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 + +# 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', 'kademlia', u'Kademlia Documentation', + [u'Brian Muller'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'Kademlia', u'Kademlia Documentation', + u'Brian Muller', 'Kademlia', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + +autoclass_content = 'both' diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..366030b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,21 @@ +.. Kademlia documentation master file, created by + sphinx-quickstart on Mon Jan 5 09:42:46 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Kademlia Documentation +====================== + +.. toctree:: + :maxdepth: 3 + + intro + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/intro.rst b/docs/intro.rst new file mode 100644 index 0000000..52fdf8f --- /dev/null +++ b/docs/intro.rst @@ -0,0 +1,4 @@ +================== +Overview / Install +================== +This is an overview. diff --git a/docs/source/kademlia.rst b/docs/source/kademlia.rst new file mode 100644 index 0000000..3f8cda1 --- /dev/null +++ b/docs/source/kademlia.rst @@ -0,0 +1,85 @@ +kademlia package +================ + +Subpackages +----------- + +.. toctree:: + + kademlia.tests + +Submodules +---------- + +kademlia.crawling module +------------------------ + +.. automodule:: kademlia.crawling + :members: + :undoc-members: + :show-inheritance: + +kademlia.log module +------------------- + +.. automodule:: kademlia.log + :members: + :undoc-members: + :show-inheritance: + +kademlia.network module +----------------------- + +.. automodule:: kademlia.network + :members: + :undoc-members: + :show-inheritance: + +kademlia.node module +-------------------- + +.. automodule:: kademlia.node + :members: + :undoc-members: + :show-inheritance: + +kademlia.protocol module +------------------------ + +.. automodule:: kademlia.protocol + :members: + :undoc-members: + :show-inheritance: + +kademlia.routing module +----------------------- + +.. automodule:: kademlia.routing + :members: + :undoc-members: + :show-inheritance: + +kademlia.storage module +----------------------- + +.. automodule:: kademlia.storage + :members: + :undoc-members: + :show-inheritance: + +kademlia.utils module +--------------------- + +.. automodule:: kademlia.utils + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: kademlia + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/kademlia.tests.rst b/docs/source/kademlia.tests.rst new file mode 100644 index 0000000..8dace30 --- /dev/null +++ b/docs/source/kademlia.tests.rst @@ -0,0 +1,38 @@ +kademlia.tests package +====================== + +Submodules +---------- + +kademlia.tests.test_node module +------------------------------- + +.. automodule:: kademlia.tests.test_node + :members: + :undoc-members: + :show-inheritance: + +kademlia.tests.test_routing module +---------------------------------- + +.. automodule:: kademlia.tests.test_routing + :members: + :undoc-members: + :show-inheritance: + +kademlia.tests.utils module +--------------------------- + +.. automodule:: kademlia.tests.utils + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: kademlia.tests + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..aed1ce0 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +kademlia +======== + +.. toctree:: + :maxdepth: 4 + + kademlia diff --git a/kademlia/network.py b/kademlia/network.py index 858b380..79117f6 100644 --- a/kademlia/network.py +++ b/kademlia/network.py @@ -26,9 +26,9 @@ class Server(object): """ Create a server instance. This will start listening on the given port. - @param port: UDP port to listen on - @param k: The k parameter from the paper - @param alpha: The alpha parameter from the paper + Args: + ksize (int): The k parameter from the paper + alpha: The alpha parameter from the paper """ self.ksize = ksize self.alpha = alpha diff --git a/setup.py b/setup.py index aab5be7..b7453c3 100755 --- a/setup.py +++ b/setup.py @@ -12,5 +12,5 @@ setup( url="http://github.com/bmuller/kademlia", packages=find_packages(), requires=["twisted", "rpcudp"], - install_requires=['twisted>=13.0', "rpcudp>=1.0"] + install_requires=['twisted>=14.0', "rpcudp>=1.0"] )