Merge pull request #104 from dbrgn/newdocs

New Sphinx Docs

.gitignore

@@ -3,6 +3,6 @@
 .ropeproject
 *.pyc
 /build/
-/docs/build/
+/docs/_build/
 /dist/
 jedi.egg-info/

README.rst

@@ -29,15 +29,15 @@ Jedi for now, you'll have to use VIM. But there are new plugins emerging:
 
 Here are some pictures:
 
-.. image:: https://github.com/davidhalter/jedi/raw/master/docs/source/screenshot_complete.png
+.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_complete.png
 
 Completion for almost anything (Ctrl+Space).
 
-.. image:: https://github.com/davidhalter/jedi/raw/master/docs/source/screenshot_function.png
+.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_function.png
 
 Display of function/class bodies, docstrings.
 
-.. image:: https://github.com/davidhalter/jedi/raw/master/docs/source/screenshot_pydoc.png
+.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_pydoc.png
 
 Pydoc support (with highlighting, Shift+k).
 
@@ -47,8 +47,7 @@ Get the latest version from `github <http://github.com/davidhalter/jedi>`_
 (master branch should always be kind of stable/working).
 
 Docs are available at `https://jedi.readthedocs.org/
-<https://jedi.readthedocs.org/>`_. Pull requests with documentation
+<https://jedi.readthedocs.org/>`_. Pull requests with documentation enhancements
-nhancements
 and/or fixes are awesome and most welcome.
 
 Jedi uses `semantic versioning <http://semver.org/>`_ starting with version
@@ -57,100 +56,17 @@ Jedi uses `semantic versioning <http://semver.org/>`_ starting with version
 Installation
 ============
 
-You can either include Jedi as a submodule in your text editor plugin (like
+See https://jedi.readthedocs.org/en/latest/docs/installation.html
-jedi-vim_ does it by default), or you
-can install Jedi systemwide.
-
-The preferred way to install the Jedi library into your system is by using
-pip_::
-
-    sudo pip install jedi
-
-If you want to install the current development version::
-
-    sudo pip install -e git://github.com/davidhalter/jedi.git#egg=jedi
 
 Note: This just installs the Jedi library, not the editor plugins. For
 information about how to make it work with your editor, refer to the
 corresponding documentation.
 
 
-Support
+Feature Support and Caveats
-=======
+===========================
 
-Jedi supports Python 2.5 up to 3.x. There is just one code base, for both
+See https://jedi.readthedocs.org/en/latest/docs/features.html
-Python 2 and 3.
-Jedi supports many of the widely used Python features:
-
-- builtin functions/classes support
-- complex module / function / class structures
-- ignores syntax and indentation errors
-- multiple returns / yields
-- tuple assignments / array indexing / dictionary indexing
-- with-statement / exceptions
-- \*args / \*\*kwargs
-- decorators / lambdas / closures
-- descriptors -> property / staticmethod / classmethod
-- generators (yield statement) / iterators
-- support for some magic methods: ``__call__``, ``__iter__``, ``__next__``,
-  ``__get__``, ``__getitem__``, ``__init__``
-- support for list.append, set.add, list.extend, etc.
-- (nested) list comprehensions / ternary expressions
-- relative imports
-- ``getattr()`` / ``__getattr__`` / ``__getattribute__``
-- function annotations (py3k feature, are ignored right now, but being parsed.
-  I don't know what to do with them.)
-- class decorators (py3k feature, are being ignored too, until I find a use
-  case, that doesn't work with Jedi)
-- simple/usual ``sys.path`` modifications
-- ``isinstance`` checks for if/while/assert
-- virtualenv support
-- infer function arguments with sphinx (and other) docstrings
-
-However, it does not yet support (and probably will in future versions, because
-they are on my todo list):
-
-- manipulations of instances outside the instance variables, without using
-  functions
-
-It does not support (and most probably will not in future versions): 
-
-- metaclasses (how could an auto-completion ever support this)
-- ``setattr()``, ``__import__()``
-- Writing to some dicts: ``globals()``, ``locals()``, ``object.__dict__``
-- evaluate ``if`` / ``while``
-
-
-Caveats
-=======
-
-This framework should work for both Python 2/3. However, some things were just
-not as *pythonic* in Python 2 as things should be. To keep things simple, some
-things have been held back:
-
-- Classes: Always Python 3 like, therefore all classes inherit from ``object``.
-- Generators: No ``next`` method. The ``__next__`` method is used instead.
-- Exceptions are only looked at in the form of ``Exception as e``, no comma!
-
-Syntax errors and other strange stuff, that is defined differently in the
-Python language, may lead to undefined behaviour of the completion. Jedi is
-**NOT** a Python compiler, that tries to correct you. It is a tool that wants
-to help you. But **YOU** have to know Python, not Jedi.
-
-Importing ``numpy`` can be quite slow sometimes, as well as loading the builtins
-the first time. If you want to speed it up, you could write import hooks in
-jedi, which preloads this stuff. However, once loaded, this is not a problem
-anymore. The same is true for huge modules like ``PySide``, ``wx``, etc.
-
-Security is an important issue for Jedi. Therefore no Python code is executed.
-As long as you write pure python, everything is evaluated statically. But: If
-you use builtin modules (`c_builtin`) there is no other option than to execute
-those modules. However: Execute isn't that critical (as e.g. in pythoncomplete,
-which used to execute *every* import!), because it means one import and no
-more. So basically the only dangerous thing is using the import itself. If your
-`c_builtin` uses some strange initializations, it might be dangerous. But if it
-does you're screwed anyways, because eventualy you're going to execute your
-code, which executes the import.
 
 
 A little history
@@ -184,82 +100,9 @@ think understanding it might need quite some time, because of its recursive
 nature.
 
 
-API-Design for IDEs
+API for IDEs
-===================
+============
 
-If you want to set up an IDE with Jedi, you need to ``import jedi``. You should
+It's very easy to create an editor plugin that uses Jedi. See
-have the following objects available:
+https://jedi.readthedocs.org/en/latest/docs/plugin-api.html for more
-
+information.
-::
-
-    Script(source, line, column, source_path)
-
-``source`` would be the source of your python file/script, separated by new
-lines. ``line`` is the current line you want to perform actions on (starting
-with line #1 as the first line). ``column`` represents the current
-column/indent of the cursor (starting with zero). ``source_path`` should be the
-path of your file in the file system.
-
-It returns a script object that contains the relevant information for the other
-functions to work without params.
-
-::
-
-    Script().complete
-
-Returns ``api.Completion`` objects. Those objects have got
-informations about the completions. More than just names.
-
-::
-
-    Script().goto
-
-Similar to complete. The returned ``api.Definition`` objects contain
-information about the definitions found.
-
-::
-
-    Script().get_definition
-
-Mostly used for tests. Like goto, but follows statements and imports and
-doesn't break there. You probably don't want to use this function. It's
-mostly for testing.
-
-::
-
-    Script().related_names
-
-Returns all names that point to the definition of the name under the
-cursor. This is also very useful for refactoring (renaming).
-
-::
-
-    Script().get_in_function_call
-
-Get the ``Function`` object of the call you're currently in, e.g.: ``abs(``
-with the cursor at the end would return the builtin ``abs`` function.
-
-::
-
-    NotFoundError
-
-If you use the goto function and no valid identifier (name) is at the
-place of the cursor (position). It will raise this exception.
-
-::
-
-    set_debug_function
-
-Sets a callback function for ``debug.py``. This function is called with
-multiple text objects, in python 3 you could insert ``print``.
-
-::
-
-    settings
-
-Access to the ``settings.py`` module. The settings are described there.
-
-
-
-.. _jedi-vim: http://github.com/davidhalter/jedi-vim
-.. _pip: http://www.pip-installer.org/

docs/Makefile

@@ -5,14 +5,14 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = build
+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) source
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 

docs/_templates/ghbuttons.html

@@ -0,0 +1,4 @@
+<h3>Github</h3>
+<iframe src="http://ghbtns.com/github-btn.html?user=davidhalter&repo=jedi&type=watch&count=true&size=large"
+        frameborder="0" scrolling="0" width="170" height="30" allowtransparency="true"></iframe>
+<br><br>

docs/_templates/sidebarlogo.html

@@ -0,0 +1,3 @@
+<p class="logo"><a href="{{ pathto(master_doc) }}">
+  <img class="logo" src="{{ pathto('_static/logo.png', 1) }}" alt="Logo"/>
+</a></p>

docs/_themes/flask/LICENSE

@@ -0,0 +1,37 @@
+Copyright (c) 2010 by Armin Ronacher.
+
+Some rights reserved.
+
+Redistribution and use in source and binary forms of the theme, 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.
+
+* The names of the contributors may not be used to endorse or
+  promote products derived from this software without specific
+  prior written permission.
+
+We kindly ask you to only use these themes in an unmodified manner just
+for Flask and Flask-related products, not for unrelated projects.  If you
+like the visual style and want to use it for your own projects, please
+consider making some larger changes to the themes (such as changing
+font faces, sizes, colors or margins).
+
+THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

docs/_themes/flask/layout.html

@@ -0,0 +1,28 @@
+{%- extends "basic/layout.html" %}
+{%- block extrahead %}
+  {{ super() }}
+  {% if theme_touch_icon %}
+  <link rel="apple-touch-icon" href="{{ pathto('_static/' ~ theme_touch_icon, 1) }}" />
+  {% endif %}
+  <link media="only screen and (max-device-width: 480px)" href="{{
+    pathto('_static/small_flask.css', 1) }}" type= "text/css" rel="stylesheet" />
+  <a href="https://github.com/davidhalter/jedi">
+    <img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png" alt="Fork me on GitHub">
+  </a>
+{% endblock %}
+{%- block relbar2 %}{% endblock %}
+{% block header %}
+  {{ super() }}
+  {% if pagename == 'index' %}
+  <div class=indexwrapper>
+  {% endif %}
+{% endblock %}
+{%- block footer %}
+  <div class="footer">
+    &copy; Copyright {{ copyright }}.
+    Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
+  </div>
+  {% if pagename == 'index' %}
+  </div>
+  {% endif %}
+{%- endblock %}

docs/_themes/flask/relations.html

@@ -0,0 +1,19 @@
+<h3>Related Topics</h3>
+<ul>
+  <li><a href="{{ pathto(master_doc) }}">Documentation overview</a><ul>
+  {%- for parent in parents %}
+  <li><a href="{{ parent.link|e }}">{{ parent.title }}</a><ul>
+  {%- endfor %}
+    {%- if prev %}
+      <li>Previous: <a href="{{ prev.link|e }}" title="{{ _('previous chapter')
+        }}">{{ prev.title }}</a></li>
+    {%- endif %}
+    {%- if next %}
+      <li>Next: <a href="{{ next.link|e }}" title="{{ _('next chapter')
+        }}">{{ next.title }}</a></li>
+    {%- endif %}
+  {%- for parent in parents %}
+  </ul></li>
+  {%- endfor %}
+  </ul></li>
+</ul>

docs/_themes/flask/static/flasky.css_t

@@ -0,0 +1,394 @@
+/*
+ * flasky.css_t
+ * ~~~~~~~~~~~~
+ *
+ * :copyright: Copyright 2010 by Armin Ronacher.
+ * :license: Flask Design License, see LICENSE for details.
+ */
+
+{% set page_width = '940px' %}
+{% set sidebar_width = '220px' %}
+ 
+@import url("basic.css");
+ 
+/* -- page layout ----------------------------------------------------------- */
+ 
+body {
+    font-family: 'Georgia', serif;
+    font-size: 17px;
+    background-color: white;
+    color: #000;
+    margin: 0;
+    padding: 0;
+}
+
+div.document {
+    width: {{ page_width }};
+    margin: 30px auto 0 auto;
+}
+
+div.documentwrapper {
+    float: left;
+    width: 100%;
+}
+
+div.bodywrapper {
+    margin: 0 0 0 {{ sidebar_width }};
+}
+
+div.sphinxsidebar {
+    width: {{ sidebar_width }};
+}
+
+hr {
+    border: 1px solid #B1B4B6;
+}
+ 
+div.body {
+    background-color: #ffffff;
+    color: #3E4349;
+    padding: 0 30px 0 30px;
+}
+
+img.floatingflask {
+    padding: 0 0 10px 10px;
+    float: right;
+}
+ 
+div.footer {
+    width: {{ page_width }};
+    margin: 20px auto 30px auto;
+    font-size: 14px;
+    color: #888;
+    text-align: right;
+}
+
+div.footer a {
+    color: #888;
+}
+
+div.related {
+    display: none;
+}
+ 
+div.sphinxsidebar a {
+    color: #444;
+    text-decoration: none;
+    border-bottom: 1px dotted #999;
+}
+
+div.sphinxsidebar a:hover {
+    border-bottom: 1px solid #999;
+}
+ 
+div.sphinxsidebar {
+    font-size: 14px;
+    line-height: 1.5;
+}
+
+div.sphinxsidebarwrapper {
+    padding: 18px 10px;
+}
+
+div.sphinxsidebarwrapper p.logo {
+    padding: 0 0 20px 0;
+    margin: 0;
+    text-align: center;
+}
+ 
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+    font-family: 'Garamond', 'Georgia', serif;
+    color: #444;
+    font-size: 24px;
+    font-weight: normal;
+    margin: 0 0 5px 0;
+    padding: 0;
+}
+
+div.sphinxsidebar h4 {
+    font-size: 20px;
+}
+ 
+div.sphinxsidebar h3 a {
+    color: #444;
+}
+
+div.sphinxsidebar p.logo a,
+div.sphinxsidebar h3 a,
+div.sphinxsidebar p.logo a:hover,
+div.sphinxsidebar h3 a:hover {
+    border: none;
+}
+ 
+div.sphinxsidebar p {
+    color: #555;
+    margin: 10px 0;
+}
+
+div.sphinxsidebar ul {
+    margin: 10px 0;
+    padding: 0;
+    color: #000;
+}
+ 
+div.sphinxsidebar input {
+    border: 1px solid #ccc;
+    font-family: 'Georgia', serif;
+    font-size: 1em;
+}
+ 
+/* -- body styles ----------------------------------------------------------- */
+ 
+a {
+    color: #004B6B;
+    text-decoration: underline;
+}
+ 
+a:hover {
+    color: #6D4100;
+    text-decoration: underline;
+}
+ 
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+    font-family: 'Garamond', 'Georgia', serif;
+    font-weight: normal;
+    margin: 30px 0px 10px 0px;
+    padding: 0;
+}
+
+{% if theme_index_logo %}
+div.indexwrapper h1 {
+    text-indent: -999999px;
+    background: url({{ theme_index_logo }}) no-repeat center center;
+    height: {{ theme_index_logo_height }};
+}
+{% endif %}
+ 
+div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; }
+div.body h2 { font-size: 180%; }
+div.body h3 { font-size: 150%; }
+div.body h4 { font-size: 130%; }
+div.body h5 { font-size: 100%; }
+div.body h6 { font-size: 100%; }
+ 
+a.headerlink {
+    color: #ddd;
+    padding: 0 4px;
+    text-decoration: none;
+}
+ 
+a.headerlink:hover {
+    color: #444;
+}
+ 
+div.body p, div.body dd, div.body li {
+    line-height: 1.4em;
+}
+
+div.admonition {
+    background: #fafafa;
+    margin: 20px -30px;
+    padding: 10px 30px;
+    border-top: 1px solid #ccc;
+    border-bottom: 1px solid #ccc;
+}
+
+div.admonition tt.xref, div.admonition a tt {
+    border-bottom: 1px solid #fafafa;
+}
+
+dd div.admonition {
+    margin-left: -60px;
+    padding-left: 60px;
+}
+
+div.admonition p.admonition-title {
+    font-family: 'Garamond', 'Georgia', serif;
+    font-weight: normal;
+    font-size: 24px;
+    margin: 0 0 10px 0;
+    padding: 0;
+    line-height: 1;
+}
+
+div.admonition p.last {
+    margin-bottom: 0;
+}
+
+div.highlight {
+    background-color: white;
+}
+
+dt:target, .highlight {
+    background: #FAF3E8;
+}
+
+div.note {
+    background-color: #eee;
+    border: 1px solid #ccc;
+}
+ 
+div.seealso {
+    background-color: #ffc;
+    border: 1px solid #ff6;
+}
+ 
+div.topic {
+    background-color: #eee;
+}
+ 
+p.admonition-title {
+    display: inline;
+}
+ 
+p.admonition-title:after {
+    content: ":";
+}
+
+pre, tt {
+    font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+    font-size: 0.9em;
+}
+
+img.screenshot {
+}
+
+tt.descname, tt.descclassname {
+    font-size: 0.95em;
+}
+
+tt.descname {
+    padding-right: 0.08em;
+}
+
+img.screenshot {
+    -moz-box-shadow: 2px 2px 4px #eee;
+    -webkit-box-shadow: 2px 2px 4px #eee;
+    box-shadow: 2px 2px 4px #eee;
+}
+
+table.docutils {
+    border: 1px solid #888;
+    -moz-box-shadow: 2px 2px 4px #eee;
+    -webkit-box-shadow: 2px 2px 4px #eee;
+    box-shadow: 2px 2px 4px #eee;
+}
+
+table.docutils td, table.docutils th {
+    border: 1px solid #888;
+    padding: 0.25em 0.7em;
+}
+
+table.field-list, table.footnote {
+    border: none;
+    -moz-box-shadow: none;
+    -webkit-box-shadow: none;
+    box-shadow: none;
+}
+
+table.footnote {
+    margin: 15px 0;
+    width: 100%;
+    border: 1px solid #eee;
+    background: #fdfdfd;
+    font-size: 0.9em;
+}
+
+table.footnote + table.footnote {
+    margin-top: -15px;
+    border-top: none;
+}
+
+table.field-list th {
+    padding: 0 0.8em 0 0;
+}
+
+table.field-list td {
+    padding: 0;
+}
+
+table.footnote td.label {
+    width: 0px;
+    padding: 0.3em 0 0.3em 0.5em;
+}
+
+table.footnote td {
+    padding: 0.3em 0.5em;
+}
+
+dl {
+    margin: 0;
+    padding: 0;
+}
+
+dl dd {
+    margin-left: 30px;
+}
+
+blockquote {
+    margin: 0 0 0 30px;
+    padding: 0;
+}
+
+ul, ol {
+    margin: 10px 0 10px 30px;
+    padding: 0;
+}
+ 
+pre {
+    background: #eee;
+    padding: 7px 30px;
+    margin: 15px -30px;
+    line-height: 1.3em;
+}
+
+dl pre, blockquote pre, li pre {
+    margin-left: -60px;
+    padding-left: 60px;
+}
+
+dl dl pre {
+    margin-left: -90px;
+    padding-left: 90px;
+}
+ 
+tt {
+    background-color: #ecf0f3;
+    color: #222;
+    /* padding: 1px 2px; */
+}
+
+tt.xref, a tt {
+    background-color: #FBFBFB;
+    border-bottom: 1px solid white;
+}
+
+a.reference {
+    text-decoration: none;
+    border-bottom: 1px dotted #004B6B;
+}
+
+a.reference:hover {
+    border-bottom: 1px solid #6D4100;
+}
+
+a.footnote-reference {
+    text-decoration: none;
+    font-size: 0.7em;
+    vertical-align: top;
+    border-bottom: 1px dotted #004B6B;
+}
+
+a.footnote-reference:hover {
+    border-bottom: 1px solid #6D4100;
+}
+
+a:hover tt {
+    background: #EEE;
+}

docs/_themes/flask/static/small_flask.css

@@ -0,0 +1,70 @@
+/*
+ * small_flask.css_t
+ * ~~~~~~~~~~~~~~~~~
+ *
+ * :copyright: Copyright 2010 by Armin Ronacher.
+ * :license: Flask Design License, see LICENSE for details.
+ */
+
+body {
+    margin: 0;
+    padding: 20px 30px;
+}
+
+div.documentwrapper {
+    float: none;
+    background: white;
+}
+
+div.sphinxsidebar {
+    display: block;
+    float: none;
+    width: 102.5%;
+    margin: 50px -30px -20px -30px;
+    padding: 10px 20px;
+    background: #333;
+    color: white;
+}
+
+div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p,
+div.sphinxsidebar h3 a {
+    color: white;
+}
+
+div.sphinxsidebar a {
+    color: #aaa;
+}
+
+div.sphinxsidebar p.logo {
+    display: none;
+}
+
+div.document {
+    width: 100%;
+    margin: 0;
+}
+
+div.related {
+    display: block;
+    margin: 0;
+    padding: 10px 0 20px 0;
+}
+
+div.related ul,
+div.related ul li {
+    margin: 0;
+    padding: 0;
+}
+
+div.footer {
+    display: none;
+}
+
+div.bodywrapper {
+    margin: 0;
+}
+
+div.body {
+    min-height: 0;
+    padding: 0;
+}

docs/_themes/flask/theme.conf

@@ -0,0 +1,9 @@
+[theme]
+inherit = basic
+stylesheet = flasky.css
+pygments_style = flask_theme_support.FlaskyStyle
+
+[options]
+index_logo = 
+index_logo_height = 120px
+touch_icon = 

docs/_themes/flask_theme_support.py

@@ -0,0 +1,125 @@
+"""
+Copyright (c) 2010 by Armin Ronacher.
+
+Some rights reserved.
+
+Redistribution and use in source and binary forms of the theme, 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.
+
+* The names of the contributors may not be used to endorse or
+  promote products derived from this software without specific
+  prior written permission.
+
+We kindly ask you to only use these themes in an unmodified manner just
+for Flask and Flask-related products, not for unrelated projects.  If you
+like the visual style and want to use it for your own projects, please
+consider making some larger changes to the themes (such as changing
+font faces, sizes, colors or margins).
+
+THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+"""
+# flasky extensions.  flasky pygments style based on tango style
+from pygments.style import Style
+from pygments.token import Keyword, Name, Comment, String, Error, \
+     Number, Operator, Generic, Whitespace, Punctuation, Other, Literal
+
+
+class FlaskyStyle(Style):
+    background_color = "#f8f8f8"
+    default_style = ""
+
+    styles = {
+        # No corresponding class for the following:
+        #Text:                     "", # class:  ''
+        Whitespace:                "underline #f8f8f8",      # class: 'w'
+        Error:                     "#a40000 border:#ef2929", # class: 'err'
+        Other:                     "#000000",                # class 'x'
+
+        Comment:                   "italic #8f5902", # class: 'c'
+        Comment.Preproc:           "noitalic",       # class: 'cp'
+
+        Keyword:                   "bold #004461",   # class: 'k'
+        Keyword.Constant:          "bold #004461",   # class: 'kc'
+        Keyword.Declaration:       "bold #004461",   # class: 'kd'
+        Keyword.Namespace:         "bold #004461",   # class: 'kn'
+        Keyword.Pseudo:            "bold #004461",   # class: 'kp'
+        Keyword.Reserved:          "bold #004461",   # class: 'kr'
+        Keyword.Type:              "bold #004461",   # class: 'kt'
+
+        Operator:                  "#582800",   # class: 'o'
+        Operator.Word:             "bold #004461",   # class: 'ow' - like keywords
+
+        Punctuation:               "bold #000000",   # class: 'p'
+
+        # because special names such as Name.Class, Name.Function, etc.
+        # are not recognized as such later in the parsing, we choose them
+        # to look the same as ordinary variables.
+        Name:                      "#000000",        # class: 'n'
+        Name.Attribute:            "#c4a000",        # class: 'na' - to be revised
+        Name.Builtin:              "#004461",        # class: 'nb'
+        Name.Builtin.Pseudo:       "#3465a4",        # class: 'bp'
+        Name.Class:                "#000000",        # class: 'nc' - to be revised
+        Name.Constant:             "#000000",        # class: 'no' - to be revised
+        Name.Decorator:            "#888",           # class: 'nd' - to be revised
+        Name.Entity:               "#ce5c00",        # class: 'ni'
+        Name.Exception:            "bold #cc0000",   # class: 'ne'
+        Name.Function:             "#000000",        # class: 'nf'
+        Name.Property:             "#000000",        # class: 'py'
+        Name.Label:                "#f57900",        # class: 'nl'
+        Name.Namespace:            "#000000",        # class: 'nn' - to be revised
+        Name.Other:                "#000000",        # class: 'nx'
+        Name.Tag:                  "bold #004461",   # class: 'nt' - like a keyword
+        Name.Variable:             "#000000",        # class: 'nv' - to be revised
+        Name.Variable.Class:       "#000000",        # class: 'vc' - to be revised
+        Name.Variable.Global:      "#000000",        # class: 'vg' - to be revised
+        Name.Variable.Instance:    "#000000",        # class: 'vi' - to be revised
+
+        Number:                    "#990000",        # class: 'm'
+
+        Literal:                   "#000000",        # class: 'l'
+        Literal.Date:              "#000000",        # class: 'ld'
+
+        String:                    "#4e9a06",        # class: 's'
+        String.Backtick:           "#4e9a06",        # class: 'sb'
+        String.Char:               "#4e9a06",        # class: 'sc'
+        String.Doc:                "italic #8f5902", # class: 'sd' - like a comment
+        String.Double:             "#4e9a06",        # class: 's2'
+        String.Escape:             "#4e9a06",        # class: 'se'
+        String.Heredoc:            "#4e9a06",        # class: 'sh'
+        String.Interpol:           "#4e9a06",        # class: 'si'
+        String.Other:              "#4e9a06",        # class: 'sx'
+        String.Regex:              "#4e9a06",        # class: 'sr'
+        String.Single:             "#4e9a06",        # class: 's1'
+        String.Symbol:             "#4e9a06",        # class: 'ss'
+
+        Generic:                   "#000000",        # class: 'g'
+        Generic.Deleted:           "#a40000",        # class: 'gd'
+        Generic.Emph:              "italic #000000", # class: 'ge'
+        Generic.Error:             "#ef2929",        # class: 'gr'
+        Generic.Heading:           "bold #000080",   # class: 'gh'
+        Generic.Inserted:          "#00A000",        # class: 'gi'
+        Generic.Output:            "#888",           # class: 'go'
+        Generic.Prompt:            "#745334",        # class: 'gp'
+        Generic.Strong:            "bold #000000",   # class: 'gs'
+        Generic.Subheading:        "bold #800080",   # class: 'gu'
+        Generic.Traceback:         "bold #a40000",   # class: 'gt'
+    }

docs/conf.py

@@ -11,13 +11,14 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys, os, datetime
 
 # 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('../..'))
+sys.path.insert(0, os.path.abspath('..'))
-sys.path.insert(0, os.path.abspath('../../jedi'))
+sys.path.insert(0, os.path.abspath('../jedi'))
+sys.path.append(os.path.abspath('_themes'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -42,10 +43,10 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Jedi'
-copyright = u'2012, Jedi contributors'
+copyright = u'2012 - {today.year}, Jedi contributors'.format(today=datetime.date.today())
 
 _path = os.path.dirname(os.path.abspath(__file__))
-with open(_path + '/../../VERSION') as f:
+with open(os.path.join(_path, '../VERSION'), 'r') as f:
     VERSION = f.read().strip()
 
 # The version info for the project you're documenting, acts as replacement for
@@ -98,7 +99,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'flask'
 
 # 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
@@ -106,7 +107,7 @@ html_theme = 'default'
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = ['_themes']
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -138,7 +139,16 @@ html_static_path = ['_static']
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+    '**': [
+#        'sidebarlogo.html',
+        'localtoc.html',
+        'relations.html',
+        'ghbuttons.html',
+        'sourcelink.html',
+        'searchbox.html'
+    ]
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -173,7 +183,7 @@ html_static_path = ['_static']
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'Jedidoc'
 
-html_style = '/default.css'  # Force usage of default template on RTD
+#html_style = 'default.css'  # Force usage of default template on RTD
 
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -256,4 +266,5 @@ todo_include_todos = False
 
 # -- Options for autodoc module ------------------------------------------------
 
+autodoc_member_order = 'bysource'
 autodoc_default_flags = ['members', 'undoc-members']

docs/docs/features.rst

@@ -0,0 +1,96 @@
+.. include:: ../global.rst
+
+Features and Caveats
+====================
+
+|jedi| supports many of the widely used Python features:
+
+
+General Features
+----------------
+
+- python 2.5+ and 3.2+ support
+- ignores syntax errors and wrong indentation
+- can deal with complex module / function / class structures
+- virtualenv support
+- can infer function arguments from sphinx and epydoc docstrings
+
+
+Supported Python Features
+-------------------------
+
+- builtins
+- multiple returns or yields
+- tuple assignments / array indexing / dictionary indexing
+- with-statement / exception handling
+- ``*args`` / ``**kwargs``
+- decorators / lambdas / closures
+- generators / iterators
+- some descriptors: property / staticmethod / classmethod
+- some magic methods: ``__call__``, ``__iter__``, ``__next__``, ``__get__``,
+  ``__getitem__``, ``__init__``
+- ``list.append()``, ``set.add()``, ``list.extend()``, etc.
+- (nested) list comprehensions / ternary expressions
+- relative imports
+- ``getattr()`` / ``__getattr__`` / ``__getattribute__``
+- function annotations (py3k feature, are ignored right now, but being parsed.
+  I don't know what to do with them.)
+- class decorators (py3k feature, are being ignored too, until I find a use
+  case, that doesn't work with |jedi|)
+- simple/usual ``sys.path`` modifications
+- ``isinstance`` checks for if/while/assert
+
+
+Unsupported Features
+--------------------
+
+Not yet implemented:
+
+- manipulations of instances outside the instance variables without using
+  methods
+
+Will probably never be implemented:
+
+- metaclasses (how could an auto-completion ever support this)
+- ``setattr()``, ``__import__()``
+- writing to some dicts: ``globals()``, ``locals()``, ``object.__dict__``
+- evaluating ``if`` / ``while``
+
+
+Caveats
+-------
+
+**Malformed Syntax**
+
+Syntax errors and other strange stuff may lead to undefined behaviour of the
+completion. |jedi| is **NOT** a Python compiler, that tries to correct you. It is
+a tool that wants to help you. But **YOU** have to know Python, not |jedi|.
+
+**Legacy Python 2 Features**
+
+This framework should work for both Python 2/3. However, some things were just
+not as *pythonic* in Python 2 as things should be. To keep things simple, some
+older Python 2 features have been left out:
+
+- Classes: Always Python 3 like, therefore all classes inherit from ``object``.
+- Generators: No ``next()`` method. The ``__next__()`` method is used instead.
+- Exceptions are only looked at in the form of ``Exception as e``, no comma!
+
+**Slow Performance**
+
+Importing ``numpy`` can be quite slow sometimes, as well as loading the builtins
+the first time. If you want to speed things up, you could write import hooks in
+|jedi|, which preload stuff. However, once loaded, this is not a problem anymore.
+The same is true for huge modules like ``PySide``, ``wx``, etc.
+
+**Security**
+
+Security is an important issue for |jedi|. Therefore no Python code is executed.
+As long as you write pure python, everything is evaluated statically. But: If
+you use builtin modules (``c_builtin``) there is no other option than to execute
+those modules. However: Execute isn't that critical (as e.g. in pythoncomplete,
+which used to execute *every* import!), because it means one import and no more.
+So basically the only dangerous thing is using the import itself. If your
+``c_builtin`` uses some strange initializations, it might be dangerous. But if
+it does you're screwed anyways, because eventualy you're going to execute your
+code, which executes the import.

docs/docs/installation.rst

@@ -1,31 +1,34 @@
+.. include:: ../global.rst
+
 Installation and Configuration
 ==============================
 
-You can either include *Jedi* as a submodule in your text editor plugin (like
+You can either include |jedi| as a submodule in your text editor plugin (like
-jedi-vim_ does it by default), or you can install it systemwide.
+jedi-vim_ does by default), or you can install it systemwide.
 
 
 System-wide installation via a package manager
 ----------------------------------------------
 
-You can install *Jedi* directly from pypi using pip::
+You can install |jedi| directly from pypi using pip::
 
     sudo pip install jedi
 
-If you want to install the current development version::
+If you want to install the current development version (master branch)::
 
     sudo pip install -e git://github.com/davidhalter/jedi.git#egg=jedi
 
-.. note:: This just installs the Jedi library, not the editor plugins. For
+.. note:: This just installs the |jedi| library, not the :ref:`editor plugins
-    information about how to make it work with your editor, refer to the
+    <editor-plugins>`. For information about how to make it work with your
-    corresponding documentation.
+    editor, refer to the corresponding documentation.
 
 
 Manual installation from a downloaded package
 ---------------------------------------------
 
-If you prefer not to use an automated package installer, you can download a
+If you prefer not to use an automated package installer, you can `download
-copy of *Jedi* and install it manually.
+<https://github.com/davidhalter/jedi/archive/master.zip>`__ a current copy of
+*Jedi* and install it manually.
 
 To install it, navigate to the directory containing `setup.py` on your console
 and type::
@@ -36,10 +39,11 @@ and type::
 Inclusion as a submodule
 ------------------------
 
-If you use an editor plugin like jedi-vim_, you can simply include *Jedi* as a
+If you use an editor plugin like jedi-vim_, you can simply include |jedi| as a
-git submodule of the plugin directory. Vim plugin managers like Vundle_ make it
+git submodule of the plugin directory. Vim plugin managers like Vundle_ or
-very easy to keep submodules up to date.
+Pathogen_ make it very easy to keep submodules up to date.
 
 
 .. _jedi-vim: https://github.com/davidhalter/jedi-vim
-.. _Vundle: https://github.com/gmarik/vundle
+.. _vundle: https://github.com/gmarik/vundle
+.. _pathogen: https://github.com/tpope/vim-pathogen

docs/docs/plugin-api.rst

@@ -1,4 +1,6 @@
-The plugin API
+.. include:: ../global.rst
+
+The Plugin API
 ==============
 
 .. currentmodule:: jedi
@@ -6,7 +8,7 @@ The plugin API
 Note: This documentation is for Plugin developers, who want to improve their
 editors/IDE autocompletion 
 
-If you want to use **Jedi**, you first need to
+If you want to use |jedi|, you first need to
 ``import jedi``. You then have direct access to the :class:`.Script`.
 
 
@@ -17,13 +19,19 @@ API Interface
 ~~~~~~~~~~~~~
 
 .. automodule:: api
-    :undoc-members:
+
 
 API Return Classes
 ~~~~~~~~~~~~~~~~~~
 
 .. automodule:: api_classes
-    :undoc-members:
+
+Settings Module
+~~~~~~~~~~~~~~~
+
+.. automodule:: settings
+    :no-members:
+    :no-undoc-members:
 
 Examples
 --------

docs/global.rst

@@ -0,0 +1,3 @@
+:orphan:
+
+.. |jedi| replace:: *Jedi*

docs/index.rst

@@ -0,0 +1,53 @@
+.. include global.rst
+
+Jedi
+====
+
+Release v\ |release|. (:doc:`Installation <docs/installation>`)
+
+.. automodule:: jedi
+
+Autocompletion can look like this (e.g. VIM plugin):
+
+.. figure:: _screenshots/screenshot_complete.png
+
+
+.. _toc:
+
+Docs
+----
+
+.. toctree::
+   :maxdepth: 1
+
+   docs/installation
+   docs/features
+   docs/plugin-api
+
+
+.. _resources:
+
+Resources
+---------
+
+- `Source Code on Github <https://github.com/davidhalter/jedi>`_
+- `Travis Testing <https://travis-ci.org/davidhalter/jedi>`_
+- `Python Package Index <http://pypi.python.org/pypi/jedi/>`_
+
+
+.. _editor-plugins:
+
+Editor Plugins
+--------------
+
+- `Vim <http://github.com/davidhalter/jedi-vim>`_
+- `Emacs <https://github.com/tkf/emacs-jedi>`_
+- `Sublime Text 2 <https://github.com/svaiter/SublimeJEDI>`_ (*under construction*)
+
+
+.. _other-software:
+
+Other Software Using Jedi
+-------------------------
+
+- `wdb <https://github.com/Kozea/wdb>`_

docs/source/index.rst

@@ -1,38 +0,0 @@
-Jedi – Python autocompletion that works!
-========================================
-
-
-About Jedi
-----------
-
-.. automodule:: jedi
-    :members:
-    :undoc-members:
-
-Autocompletion can look like this (e.g. VIM plugin):
-
-.. figure:: screenshot_complete.png
-   :align: center
-
-Contents
---------
-
-.. toctree::
-   :maxdepth: 1
-
-   installation
-   plugin-api
-
-Resources
----------
-- `Source Code on github <https://github.com/davidhalter/jedi>`_
-- `Travis testing <https://travis-ci.org/davidhalter/jedi>`_
-- `Current PyPi package <http://pypi.python.org/pypi/jedi/>`_
-
-Plugins using the Jedi library
-------------------------------
-
-- `VIM-Plugin <http://github.com/davidhalter/jedi-vim>`_
-- `Emacs-Plugin <https://github.com/tkf/emacs-jedi>`_
-- `Sublime-Plugin <https://github.com/svaiter/SublimeJEDI>`_ **Under construction**
-- `wdb (web debugger) <https://github.com/Kozea/wdb>`_

jedi/__init__.py

@@ -1,10 +1,10 @@
 """
-Jedi is an autocompletion library for Python. It offers additonal
+Jedi is an autocompletion library for Python. It also offers additional
-services such as goto / get_definition / pydoc support /
+services such as goto / get_definition / pydoc support / get_in_function_call /
-get_in_function_call / related names.
+related names.
 
-To give you a simple exmple how you can use the jedi library,
+To give you a simple example how you can use the jedi library, here is an
-here is an exmple for the autocompletion feature:
+example for the autocompletion feature:
 
 >>> import jedi
 >>> source = '''import json; json.l'''
@@ -19,9 +19,8 @@ here is an exmple for the autocompletion feature:
 >>> completions[0].word
 'load'
 
-As you see Jedi is pretty simple and allows you to concentrate
+As you see Jedi is pretty simple and allows you to concentrate on writing a
-writing a good text editor, while still having very good IDE features
+good text editor, while still having very good IDE features for Python.
-for Python.
 """
 
 import sys

jedi/api.py

@@ -1,9 +1,10 @@
 """
-The api basically only provides one class. You can create a :class:`Script` and
+The API basically only provides one class. You can create a :class:`Script` and
-use it's ``complete`` / ``goto`` / etc functions.
+use its methods.
+
 Additionally you can add a debug function with :func:`set_debug_function` and
-catch :exc:`NotFoundError` which is being raised if your completion is
+catch :exc:`NotFoundError` which is being raised if your completion is not
-impossible.
+possible.
 """
 from __future__ import with_statement
 __all__ = ['Script', 'NotFoundError', 'set_debug_function']
@@ -35,7 +36,7 @@ class NotFoundError(Exception):
 class Script(object):
     """
     A Script is the base for a completion, goto or whatever you want to do with
-    jedi.
+    |jedi|.
 
     :param source: The source code of the current file, separated by newlines.
     :type source: string
@@ -71,7 +72,7 @@ class Script(object):
         Return :class:`api_classes.Completion` objects. Those objects contain
         information about the completions, more than just names.
 
-        :return: completion objects, sorted by name and __ comes last.
+        :return: Completion objects, sorted by name and __ comes last.
         :rtype: list of :class:`api_classes.Completion`
         """
         def follow_imports_if_possible(name):

jedi/api_classes.py

@@ -1,6 +1,7 @@
-"""`api_classes` contains the return classes of the API. These classes are the
+"""
-much bigger part of the whole API, because here you get out the information
+The :mod:`api_classes` module contains the return classes of the API. These
-about completion and goto operations.
+classes are the much bigger part of the whole API, because they contain the
+interesting information about completion and goto operations.
 """
 
 import re
@@ -20,7 +21,7 @@ import keywords
 
 def _clear_caches():
     """
-    Clears all caches of this and related modules. The only cache that will not
+    Clear all caches of this and related modules. The only cache that will not
     be deleted is the module cache.
     """
     cache.clear_caches()
@@ -231,7 +232,7 @@ class Completion(BaseDefinition):
     def follow_definition(self):
         """
         Return the original definitions. I strongly recommend not using it for
-        your completions, because it might slow down *Jedi*. If you want to read
+        your completions, because it might slow down |jedi|. If you want to read
         only a few objects (<=20), it might be useful, especially to
         get the original docstrings. The basic problem of this function is
         that it follows all results. This means with 1000 completions (e.g.

jedi/settings.py

@@ -1,112 +1,224 @@
+"""
+This module contains variables with global |jedi| setting. To change the
+behavior of |jedi|, change the variables defined in
+:mod:`jedi.settings`.
+
+Plugins should expose an interface so that the user can adjust the
+configuration.
+
+
+Example usage::
+
+    from jedi import settings
+    settings.case_insensitive_completion = True
+
+
+Completion output
+~~~~~~~~~~~~~~~~~
+
+.. autodata:: case_insensitive_completion
+.. autodata:: add_dot_after_module
+.. autodata:: add_bracket_after_function
+.. autodata:: no_completion_duplicates
+
+
+Parser
+~~~~~~
+
+.. autodata:: fast_parser
+.. autodata:: fast_parser_always_reparse
+.. autodata:: use_get_in_function_call_cache
+
+
+Dynamic stuff
+~~~~~~~~~~~~~
+
+.. autodata:: dynamic_arrays_instances
+.. autodata:: dynamic_array_additions
+.. autodata:: dynamic_params
+.. autodata:: dynamic_params_for_other_modules
+.. autodata:: additional_dynamic_modules
+
+
+Recursions
+~~~~~~~~~~
+
+Recursion settings are important if you don't want extremly
+recursive python code to go absolutely crazy. First of there is a
+global limit :data:`max_executions`. This limit is important, to set
+a maximum amount of time, the completion may use.
+
+The default values are based on experiments while completing the |jedi| library
+itself (inception!). But I don't think there's any other Python library that
+uses recursion in a similarly extreme way. These settings make the completion
+definitely worse in some cases. But a completion should also be fast.
+
+.. autodata:: max_until_execution_unique
+.. autodata:: max_function_recursion_level
+.. autodata:: max_executions_without_builtins
+.. autodata:: max_executions
+.. autodata:: scale_get_in_function_call
+
+
+Caching
+~~~~~~~
+
+.. autodata:: star_import_cache_validity
+.. autodata:: get_in_function_call_validity
+
+
+Various
+~~~~~~~
+
+.. autodata:: part_line_length
+
+
+"""
+
 # ----------------
 # completion output settings
 # ----------------
 
-# The completion is by default case insensitive.
 case_insensitive_completion = True
+"""
+The completion is by default case insensitive.
+"""
 
-# Adds a dot after a module, because a module that is not accessed this way is
-# definitely not the normal case. However, in VIM this doesn't work, that's why
-# it isn't used at the moment.
 add_dot_after_module = False
+"""
+Adds a dot after a module, because a module that is not accessed this way is
+definitely not the normal case. However, in VIM this doesn't work, that's why
+it isn't used at the moment.
+"""
 
-# Adds an opening bracket after a function, because that's normal behaviour.
-# Removed it again, because in VIM that is not very practical.
 add_bracket_after_function = False
+"""
+Adds an opening bracket after a function, because that's normal behaviour.
+Removed it again, because in VIM that is not very practical.
+"""
 
-# If set, completions with the same name don't appear in the output anymore,
-# but are in the `same_name_completions` attribute.
 no_completion_duplicates = True
+"""
+If set, completions with the same name don't appear in the output anymore,
+but are in the `same_name_completions` attribute.
+"""
 
 # ----------------
 # parser
 # ----------------
 
-# Use the fast parser. This means that reparsing is only being done if
-# something has been changed e.g. to a function. If this happens, only the
-# function is being reparsed.
 fast_parser = True
+"""
+Use the fast parser. This means that reparsing is only being done if
+something has been changed e.g. to a function. If this happens, only the
+function is being reparsed.
+"""
 
-# This is just a debugging option. Always reparsing means that the fast parser
-# is basically useless. So don't use it.
 fast_parser_always_reparse = False
+"""
+This is just a debugging option. Always reparsing means that the fast parser
+is basically useless. So don't use it.
+"""
 
-# Use the cache (full cache) to generate get_in_function_call's. This may fail
-# with multiline docstrings (likely) and other complicated changes (unlikely).
-# The goal is to move away from it by making the rest faster.
 use_get_in_function_call_cache = True
+"""
+Use the cache (full cache) to generate get_in_function_call's. This may fail
+with multiline docstrings (likely) and other complicated changes (unlikely).
+The goal is to move away from it by making the rest faster.
+"""
 
 # ----------------
 # dynamic stuff
 # ----------------
 
-# check for `append`, etc. on array instances like list()
 dynamic_arrays_instances = True
-# check for `append`, etc. on arrays: [], {}, ()
+"""
+Check for `append`, etc. on array instances like list()
+"""
+
 dynamic_array_additions = True
+"""
+check for `append`, etc. on arrays: [], {}, ()
+"""
 
-# A dynamic param completion, finds the callees of the function, which define
-# the params of a function.
 dynamic_params = True
-# Do the same for other modules.
+"""
-dynamic_params_for_other_modules = True
+A dynamic param completion, finds the callees of the function, which define
+the params of a function.
+"""
+
+dynamic_params_for_other_modules = True
+"""
+Do the same for other modules.
+"""
 
-# Additional modules in which Jedi checks if statements are to be found. This
-# is practical for IDE's, that want to administrate their modules themselves.
 additional_dynamic_modules = []
+"""
+Additional modules in which |jedi| checks if statements are to be found. This
+is practical for IDEs, that want to administrate their modules themselves.
+"""
 
 # ----------------
 # recursions
 # ----------------
 
-# Recursion settings are important if you don't want extremly recursive python
+max_until_execution_unique = 50
-# code to go absolutely crazy. First of there is a global limit
+"""
-# `max_executions`. This limit is important, to set a maximum amount of time,
+This limit is probably the most important one, because if this limit is
-# the completion may use.
+exceeded, functions can only be one time executed. So new functions will be
-#
+executed, complex recursions with the same functions again and again, are
-# The `max_until_execution_unique` limit is probably the most important one,
+ignored.
-# because if that limit is passed, functions can only be one time executed. So
+"""
-# new functions will be executed, complex recursions with the same functions
-# again and again, are ignored.
-#
-# `max_function_recursion_level` is more about whether the recursions are
-# stopped in deepth or in width. The ratio beetween this and
-# `max_until_execution_unique` is important here. It stops a recursion (after
-# the number of function calls in the recursion), if it was already used
-# earlier.
-#
-# The values are based on my experimental tries, used on the jedi library. But
-# I don't think there's any other Python library, that uses recursion in a
-# similar (extreme) way. This makes the completion definitely worse in some
-# cases. But a completion should also be fast.
 
 max_function_recursion_level = 5
-max_until_execution_unique = 50
+"""
-max_executions_without_builtins = 200
+`max_function_recursion_level` is more about whether the recursions are
-max_executions = 250
+stopped in deepth or in width. The ratio beetween this and
+`max_until_execution_unique` is important here. It stops a recursion (after
+the number of function calls in the recursion), if it was already used
+earlier.
+"""
+
+max_executions_without_builtins = 200
+"""
+.. todo:: Document this.
+"""
+
+max_executions = 250
+"""
+A maximum amount of time, the completion may use.
+"""
 
-# Because get_in_function_call is normally used on every single key hit, it has
-# to be faster than a normal completion. This is the factor that is used to
-# scale `max_executions` and `max_until_execution_unique`:
 scale_get_in_function_call = 0.1
+"""
+Because get_in_function_call is normally used on every single key hit, it has
+to be faster than a normal completion. This is the factor that is used to
+scale `max_executions` and `max_until_execution_unique`:
+"""
 
 # ----------------
 # various
 # ----------------
 
-# Size of the current code part, which is used to speed up parsing.
 part_line_length = 20
+"""
+Size of the current code part, which is used to speed up parsing.
+"""
 
 # ----------------
 # caching validity (time)
 # ----------------
 
-# In huge packages like numpy, checking all star imports on every completion
-# might be slow, therefore we do a star import caching, that lasts a certain
-# time span (in seconds).
 
 star_import_cache_validity = 60.0
+"""
+In huge packages like numpy, checking all star imports on every completion
+might be slow, therefore we do a star import caching, that lasts a certain
+time span (in seconds).
+"""
 
-# Finding function calls might be slow (0.1-0.5s). This is not acceptible for
-# normal writing. Therefore cache it for a short time.
 get_in_function_call_validity = 3.0
+"""
+Finding function calls might be slow (0.1-0.5s). This is not acceptible for
+normal writing. Therefore cache it for a short time.
+"""