From cd4727ea9cbe72051e349137ea99c05c00966fd8 Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Sun, 30 Dec 2012 03:30:56 +0100 Subject: [PATCH] Added global.rst with jedi macro --- docs/docs/features.rst | 14 ++++++++------ docs/docs/installation.rst | 30 +++++++++++++++++------------- docs/docs/plugin-api.rst | 4 +++- docs/global.rst | 3 +++ docs/index.rst | 14 ++++++++++++-- 5 files changed, 43 insertions(+), 22 deletions(-) create mode 100644 docs/global.rst diff --git a/docs/docs/features.rst b/docs/docs/features.rst index 02489cd7..21c34b65 100644 --- a/docs/docs/features.rst +++ b/docs/docs/features.rst @@ -1,7 +1,9 @@ +.. include:: ../global.rst + Features and Caveats ==================== -Jedi supports many of the widely used Python features: +|jedi| supports many of the widely used Python features: General Features @@ -34,7 +36,7 @@ Supported Python Features - 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) + case, that doesn't work with |jedi|) - simple/usual ``sys.path`` modifications - ``isinstance`` checks for if/while/assert @@ -61,8 +63,8 @@ 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. +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** @@ -78,12 +80,12 @@ older Python 2 features have been left out: 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. +|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. +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, diff --git a/docs/docs/installation.rst b/docs/docs/installation.rst index c8f0099c..60df49be 100644 --- a/docs/docs/installation.rst +++ b/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 -jedi-vim_ does it by default), or you can install it systemwide. +You can either include |jedi| as a submodule in your text editor plugin (like +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 - information about how to make it work with your editor, refer to the - corresponding documentation. +.. note:: This just installs the |jedi| library, not the :ref:`editor plugins + `. For information about how to make it work with your + 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 -copy of *Jedi* and install it manually. +If you prefer not to use an automated package installer, you can `download +`__ 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 -git submodule of the plugin directory. Vim plugin managers like Vundle_ make it -very easy to keep submodules up to date. +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_ or +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 diff --git a/docs/docs/plugin-api.rst b/docs/docs/plugin-api.rst index f5bc1aa2..3b4e3f40 100644 --- a/docs/docs/plugin-api.rst +++ b/docs/docs/plugin-api.rst @@ -1,3 +1,5 @@ +.. include:: ../global.rst + The Plugin API ============== @@ -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`. diff --git a/docs/global.rst b/docs/global.rst new file mode 100644 index 00000000..0279842a --- /dev/null +++ b/docs/global.rst @@ -0,0 +1,3 @@ +:orphan: + +.. |jedi| replace:: *Jedi* diff --git a/docs/index.rst b/docs/index.rst index d7218f8d..ca665675 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,3 +1,5 @@ +.. include global.rst + Jedi ==== @@ -12,6 +14,8 @@ Autocompletion can look like this (e.g. VIM plugin): .. figure:: _screenshots/screenshot_complete.png +.. _toc: + Docs ---- @@ -23,6 +27,8 @@ Docs docs/plugin-api +.. _resources: + Resources --------- @@ -31,14 +37,18 @@ Resources - `Python Package Index `_ -Text Editor Plugins -------------------- +.. _editor-plugins: + +Editor Plugins +-------------- - `Vim `_ - `Emacs `_ - `Sublime Text 2 `_ (*under construction*) +.. _other-software: + Other Software Using Jedi -------------------------