diff --git a/README.rst b/README.rst index 60ba2ae1..dd61a3eb 100644 --- a/README.rst +++ b/README.rst @@ -1,29 +1,13 @@ -========= Powerline ========= :Author: Kim Silkebækken (kim.silkebaekken+vim@gmail.com) :Source: https://github.com/Lokaltog/powerline +:Version: beta -**This is alpha software, expect things to change or break at any point.** +This is the next version of Powerline, implemented in Python. The project is +currently in beta, and most of the functionality in the old vimscript +project is already implemented. -This is the next version of Powerline, implemented in Python. It aims to -resolve some of the "unresolvable" problems of the vimscript implementation, -as well as providing a common code base for all projects that use Powerline -in some way (e.g. shell prompts and tmux themes). - -Some of the new features for vim are: - -* **Dynamic statusline evaluation in Python.** Python performs really well - and allows Powerline to re-render the statusline in Python instead of - relying on vim's statusline flags. This means no more caching, and much - more flexibility. -* **Automatic removal of less important segments in small windows.** Not all - information is equally important to have in the statusline, and segments - with e.g. encoding and file format information are automatically removed - in smaller windows. -* **The possibility of adding more segments.** Because of vim's hardcoded - limitation of 80 statusline options, the vimscript implementation - triggered an error when adding more segments to the default theme. Since - segment contents are now rendered as plain text in Python it's possible to - add many more segments in the statusline before hitting this limit. +Check out the `documentation `_ for +more information and installation instructions. diff --git a/docs/source/conf.py b/docs/source/conf.py index 05947c04..be00d779 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -9,8 +9,8 @@ source_suffix = '.rst' master_doc = 'index' project = u'Powerline' copyright = u'Kim Silkebækken' -version = 'dev' -release = 'dev' +version = 'beta' +release = 'beta' exclude_patterns = ['_build'] pygments_style = 'sphinx' html_theme = 'nature' diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 839f6004..6e79ebdf 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -1,4 +1,2 @@ Configuration ============= - -.. include:: configuration/vim.rst diff --git a/docs/source/configuration/vim.rst b/docs/source/configuration/vim.rst deleted file mode 100644 index c5fea4e6..00000000 --- a/docs/source/configuration/vim.rst +++ /dev/null @@ -1,2 +0,0 @@ -Vim configuration ------------------ diff --git a/docs/source/fontpatching.rst b/docs/source/fontpatching.rst new file mode 100644 index 00000000..066369e0 --- /dev/null +++ b/docs/source/fontpatching.rst @@ -0,0 +1,2 @@ +Font patching +============= diff --git a/docs/source/index.rst b/docs/source/index.rst index 56e71c0f..5f1e50ee 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,7 +7,10 @@ Powerline introduction overview + fontpatching configuration + troubleshooting + license-credits Indices and tables ================== diff --git a/docs/source/installation/vim.rst b/docs/source/installation/vim.rst deleted file mode 100644 index 2d6d4bd9..00000000 --- a/docs/source/installation/vim.rst +++ /dev/null @@ -1,20 +0,0 @@ -Vim installation ----------------- - -As a system-wide Python package -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Add the following line to your ``vimrc``:: - - python import plugin.vim.load_vim_plugin - -Outside Python's search path -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This requires you to source the plugin file with an absolute path to the -plugin location. - -Add the following line to your ``vimrc``, where ``{path}`` is the path to -the main Powerline project folder:: - - source {path}/plugin/vim/powerline.vim diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index c516b331..07ba4f2a 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -1,2 +1,37 @@ Introduction ============ + +This is the next version of Powerline, implemented in Python. It aims to +resolve some of the "unresolvable" problems of the vimscript implementation, +as well as providing a common code base for all projects that use Powerline +in some way (e.g. shell prompts and tmux themes). + +The project is currently in beta, and most of the functionality in the old +vimscript project is already implemented. + +Feature highlights +------------------ + +* **Better performance.** Python performs quite a bit better than vimscript, + and by having most of the code in Python instead of vimscript it's also + much easier to profile the code and eliminate bottlenecks. +* **A much leaner code base.** With most of the functionality of the old + project implemented the new version consists of less than half the amount + of code. +* **Automatic removal of less important segments in small windows.** Not all + information is equally important to have in the statusline, and segments + with e.g. encoding and file format information are automatically removed + in smaller windows. +* **Dynamic statusline evaluation in Python.** Statuslines are dynamically + rendered in Python instead of relying on vim's statusline flags, which + allows much more flexibility when creating statuslines. +* **The possibility of adding more segments.** Because of vim's hardcoded + limitation of 80 statusline options, the vimscript implementation + triggered an error when adding more segments to the default theme. Since + segment contents are now rendered as plain text in Python it's possible to + add many more segments in the statusline before reaching this limit. +* **New and improved theme and colorscheme syntax.** Themes and colorschemes + are now written in JSON, with a much cleaner syntax that's easier to learn + and work with. Themes and colorschemes are also much more configurable, + and it's easy to write your own and store them in your home config + directory (usually ``~/.config/powerline``). diff --git a/docs/source/licence-credits.rst b/docs/source/licence-credits.rst new file mode 100644 index 00000000..8db542bb --- /dev/null +++ b/docs/source/licence-credits.rst @@ -0,0 +1,40 @@ +License +======= + +.. image:: http://i.creativecommons.org/l/by-sa/3.0/88x31.png + :target: `Creative Commons Attribution-ShareAlike 3.0 Unported License`_ + +Powerline is licensed under a `Creative Commons Attribution-ShareAlike 3.0 +Unported License`_. + +.. _`Creative Commons Attribution-ShareAlike 3.0 Unported License`: http://creativecommons.org/licenses/by-sa/3.0/ + +Credits +======= + +:Author: `Kim Silkebækken `_ +:Main contributors: + * `ZyX-I `_ + +Contributing +============ + +If you experience any bugs or have any feature requests, please `open an +issue on GitHub `_. + +Pull request guidelines +----------------------- + +This project uses `Git Flow`_ for maintaining a clean history and +a consistent way of branching and merging new features. All commit messages +must follow the guidelines described in `Tim Pope's blog post about git +commit messages`_. + +All code must use tabs for indentation and spaces for alignment. + +Python code must pass flake8 tests with ``flake8 --ignore=W191,E501`` (ignore +tab warnings and line length errors). + +.. _`Git Flow`: http://nvie.com/posts/a-successful-git-branching-model/ +.. _`Tim Pope's blog post about git commit messages`: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html + diff --git a/docs/source/overview.rst b/docs/source/overview.rst index 6c6ed9f3..87caf07d 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -4,16 +4,45 @@ Overview Requirements ------------ +Powerline requires Python 2.7 to work. + +Vim plugin requirements +^^^^^^^^^^^^^^^^^^^^^^^ + +The vim plugin requires a vim version with Python 2.7 support compiled in. +You can check if your vim supports Python 2 by running ``vim --version +| grep +python``. + +Vim version 7.3.661 or newer is recommended for performance reasons. + Installation ------------ Powerline is intended to be installed as a system-wide Python package that can be easily included in other projects. +Powerline is available `on the AUR +`_ for Arch Linux users. + .. note:: This project is currently unavailable on the PyPI due to a naming conflict with an unrelated project. -.. include:: installation/vim.rst - Usage ----- + +Vim usage +^^^^^^^^^ + +If Powerline is installed as a system-wide Python package, you can enable +the plugin by adding the following line to your ``vimrc``:: + + python import powerline.plugin.vim.load_vim_plugin + +If Powerline is installed outside Python's search path (e.g. by having the +git repo in your dotfiles folder) you'll have to source the vim plugin file +with an absolute path to the plugin location. + +Add the following line to your ``vimrc``, where ``{path}`` is the path to +the main Powerline project folder:: + + source {path}/powerline/plugin/vim/powerline.vim diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst new file mode 100644 index 00000000..4edddddf --- /dev/null +++ b/docs/source/troubleshooting.rst @@ -0,0 +1,2 @@ +Troubleshooting +=============== diff --git a/setup.py b/setup.py index 80e099d4..35375bdf 100755 --- a/setup.py +++ b/setup.py @@ -19,7 +19,7 @@ docs_extras = [ ] setup(name='Powerline', - version='β', + version='beta', description='The ultimate statusline/prompt utility.', long_description=README, classifiers=[],