Simplify s:find_start_of_block

[etc/vim.git] / README.rst

diff --git a/README.rst b/README.rst
index b9f07080779fb33d87e2ab1e5a81e00d692b82a5..77be58ccc58d48498300cf3845e2f780c7c042be 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -1,10 +1,12 @@
 vim-python-pep8-indent
 ======================
 
 vim-python-pep8-indent
 ======================
 

-.. image:: https://travis-ci.org/hynek/vim-python-pep8-indent.png?branch=travis
-   :target: https://travis-ci.org/hynek/vim-python-pep8-indent
+.. image:: https://circleci.com/gh/Vimjas/vim-python-pep8-indent.svg?style=svg
+  :target: https://circleci.com/gh/Vimjas/vim-python-pep8-indent
+.. image:: https://codecov.io/gh/Vimjas/vim-python-pep8-indent/branch/master/graph/badge.svg
+  :target: https://codecov.io/gh/Vimjas/vim-python-pep8-indent

 
 

-This small script modifies vim_’s indentation behavior to comply with PEP8_ and my aesthetic preferences.
+This small script modifies Vim_’s indentation behavior to comply with PEP8_ and my aesthetic preferences.

 Most importantly::
 
    foobar(foo,
 Most importantly::
 
    foobar(foo,


@@ -21,6 +23,8 @@ and::
 Installation
 ------------
 
 Installation
 ------------
 

+Install the plugin using your favorite plugin manager / method, a few examples
+follow:

 
 Pathogen
 ^^^^^^^^
 
 Pathogen
 ^^^^^^^^


@@ -30,7 +34,7 @@ Follow the instructions on installing Pathogen_ and then:
 .. code-block:: shell-session
 
    $ cd ~/.vim/bundle
 .. code-block:: shell-session
 
    $ cd ~/.vim/bundle

-   $ git clone https://github.com/hynek/vim-python-pep8-indent.git
+   $ git clone https://github.com/Vimjas/vim-python-pep8-indent.git

 
 
 Vundle
 
 
 Vundle


@@ -40,7 +44,7 @@ Follow the instructions on installing Vundle_ and add the appropriate plugin lin
 
 .. code-block:: vim
 
 
 .. code-block:: vim
 

-   Plugin 'hynek/vim-python-pep8-indent'
+   Plugin 'Vimjas/vim-python-pep8-indent'

 
 
 NeoBundle
 
 
 NeoBundle


@@ -50,7 +54,70 @@ Follow the instructions on installing NeoBundle_ and add the appropriate NeoBund
 
 .. code-block:: vim
 
 
 .. code-block:: vim
 

-   NeoBundle 'hynek/vim-python-pep8-indent'
+   NeoBundle 'Vimjas/vim-python-pep8-indent'
+
+
+Configuration
+-------------
+
+g:python_pep8_indent_multiline_string
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can configure the initial indentation of multiline strings using ``g:python_pep8_indent_multiline_string`` (which can also be set per buffer).
+This defaults to ``0``, which means that multiline strings are not indented.
+``-1`` and positive values will be used as-is, where ``-1`` is a special value for Vim's ``indentexpr``, and will keep the existing indent (using Vim's ``autoindent`` setting).
+``-2`` is meant to be used for strings that are wrapped with ``textwrap.dedent`` etc.  It will add a level of indentation if the multiline string started in the previous line, without any content in it already::
+
+   testdir.makeconftest("""
+       _
+
+With content already, it will be aligned to the opening parenthesis::
+
+   testdir.makeconftest("""def pytest_addoption(parser):
+                        _
+
+Existing indentation (including ``0``) in multiline strings will be kept, so this setting only applies to the indentation of new/empty lines.
+
+g:python_pep8_indent_hang_closing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Control closing bracket indentation with ``python_pep8_indent_hang_closing``, set globally or per buffer.
+
+By default (set to ``0``), closing brackets line up with the opening line::
+
+   my_list = [
+       1, 2, 3,
+       4, 5, 6,
+   ]
+   result = some_function_that_takes_arguments(
+       'a', 'b', 'c',
+       'd', 'e', 'f',
+   )
+
+With ``python_pep8_indent_hang_closing = 1``, closing brackets line up with the items::
+
+   my_list = [
+       1, 2, 3,
+       4, 5, 6,
+       ]
+   result = some_function_that_takes_arguments(
+       'a', 'b', 'c',
+       'd', 'e', 'f',
+       )
+
+
+Troubleshooting
+---------------
+
+In case it is not working, please make sure your Vim is configured to load
+indent files (``filetype indent on``).
+This is typically the case when using a plugin manager, but check its docs.
+
+Check ``:verbose set indentexpr?`` in a Python file, which should show
+something like the following:
+
+  indentexpr=GetPythonPEPIndent(v:lnum)
+        Last set from ~/…/plugged/vim-python-pep8-indent/indent/python.vim

 
 
 Notes
 
 
 Notes


@@ -86,7 +153,7 @@ While my Vimscript_ skills are still feeble, I intend to maintain it for now.
 This mainly means that I’ll triage through bugs and pull requests but won’t be fixing much myself.
 
 
 This mainly means that I’ll triage through bugs and pull requests but won’t be fixing much myself.
 
 

-.. _vim: http://www.vim.org/
+.. _Vim: http://www.vim.org/

 .. _PEP8: http://www.python.org/dev/peps/pep-0008/
 .. _`script repo`: http://www.vim.org/scripts/script.php?script_id=974
 .. _`Steve Losh`: http://stevelosh.com/
 .. _PEP8: http://www.python.org/dev/peps/pep-0008/
 .. _`script repo`: http://www.vim.org/scripts/script.php?script_id=974
 .. _`Steve Losh`: http://stevelosh.com/


@@ -99,4 +166,4 @@ This mainly means that I’ll triage through bugs and pull requests but won’t
 .. _me: https://hynek.me/
 .. _CC0: http://creativecommons.org/publicdomain/zero/1.0/
 .. _contributed: https://github.com/hynek/vim-python-pep8-indent/blob/master/CONTRIBUTING.rst
 .. _me: https://hynek.me/
 .. _CC0: http://creativecommons.org/publicdomain/zero/1.0/
 .. _contributed: https://github.com/hynek/vim-python-pep8-indent/blob/master/CONTRIBUTING.rst

-.. _`generous people`: https://github.com/hynek/vim-python-pep8-indent/blob/master/AUTHORS.rst
+.. _`generous people`: https://github.com/hynek/vim-python-pep8-indent/graphs/contributors