Polish the docs a bit

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
deleted file mode 100644 (file)
index 74fe90d..0000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# How To Contribute
-
-“vim-python-pep8-indent” is always open for suggestions and contributions by generous developers. I’ve collected a few tipps to get you started.
-
-Please:
-
-- *Always* add tests for your code.
-- Add yourself to the AUTHORS.rst file in an alphabetical fashion by first name – no matter how big or small your changes are.
-- Write [good commit messages].
-- Ideally, [squash] your commits, i.e. make your pull requests just one commit.
-
-## Running Tests
-
-- They are written in ruby (sorry :() using [vimrunner] which requires [rspec]
-- The tests go into `spec/indent/indent_spec.rb`.
-  Look at the `describe` blocks to get the hang of it.
-- Run the tests with the command `rspec spec`
-
-Thank you for considering to contribute!
-
-
-[squash]: http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
-[good commit messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
-[vimrunner]: https://github.com/AndrewRadev/vimrunner
-[rspec]: https://github.com/rspec/rspec

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
new file mode 100644 (file)
index 0000000..8e1fc2f
--- /dev/null
+++ b/CONTRIBUTING.rst
@@ -0,0 +1,30 @@
+How To Contribute
+=================
+
+``vim-python-pep8-indent`` is always open for suggestions and contributions by generous developers.
+I’ve collected a few tips to get you started.
+
+Please:
+
+- *Always* add tests for your code.
+- Add yourself to the AUTHORS.rst file in an alphabetical fashion by first name – no matter how big or small your changes are.
+- Write `good commit messages`_.
+
+
+Running Tests
+-------------
+
+- They are written in Ruby_ (sorry :() using vimrunner_ which requires rspec_.
+- The tests go into ``spec/indent/indent_spec.rb``.
+  Look at the ``describe`` blocks to get the hang of it.
+- Run the tests with the command::
+
+   $ rspec spec
+
+Thank you for considering to contribute!
+
+
+.. _Ruby: https://www.ruby-lang.org/
+.. _`good commit messages`: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+.. _vimrunner: https://github.com/AndrewRadev/vimrunner
+.. _rspec: https://github.com/rspec/rspec

diff --git a/README.rst b/README.rst
index 917b40a255d0b9e5bc7968f1d98d107ad61abf17..6ffaeb6d8e109172bff433e85c0f590edf1979dc 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -2,69 +2,87 @@ 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
+   :target: https://travis-ci.org/hynek/vim-python-pep8-indent
 
-This small script modifies vim_’s indentation behavior to comply with PEP8_ and
-my aesthetic preferences: :: python
+This small script modifies vim_’s indentation behavior to comply with PEP8_ and my aesthetic preferences.
+Most importantly::
 
-foobar(foo,
-       bar)
+   foobar(foo,
+         bar)
 
-and :: python
+and::
 
-foobar(
-    foo,
-    bar
-)
+   foobar(
+      foo,
+      bar
+   )
 
-It was *not* originally written by me. I have found the script in vim’s `script
-repo`_, however the indentation was off by one character in the first case.
-
-I fixed it with the help of `Steve Losh`_ and am putting it out here so you
-don’t have to patch the original. The original patch is still available here_.
-
-While my Vimscript_ skills are still feeble, I intend to maintain it for now.
-So feel free to report bugs, I’ll try to address them as well as I can,
-provided they fit into the scope of this project.
-
-Unfortunately, I wasn’t able to reach any of the original authors/maintainers:
-**David Bustos** and **Eric Mc Sween**. I’d like to thank them here for their
-work and release it hereby to the *Public Domain*. If anyone with a say in this
-objects, please let me know.
 
 Installation
 ------------
 
+
 Pathogen
-########
-Follow the instructions on installing Pathogen_ and then :: 
+^^^^^^^^
+
+Follow the instructions on installing Pathogen_ and then:
+
+.. code-block:: shell-session
+
+   $ cd ~/.vim/bundle
+   $ git clone https://github.com/hynek/vim-python-pep8-indent.git
 
-cd ~/.vim/bundle
-git clone https://github.com/hynek/vim-python-pep8-indent.git
 
 Vundle
 ######
 
-Follow the instructions on installing Vundle_ and add the appropriate
-plugin line: ::
+Follow the instructions on installing Vundle_ and add the appropriate plugin line into your ``.vimrc``:
+
+.. code-block:: vim
+
+   Plugin 'hynek/vim-python-pep8-indent'
 
-Plugin 'hynek/vim-python-pep8-indent`
 
 NeoBundle
 #########
 
-Follow the instructions on installing NeoBundle_ and add the appropriate
-NeoBundle line: ::
+Follow the instructions on installing NeoBundle_ and add the appropriate NeoBundle line into your ``.vimrc``:
+
+.. code-block:: vim
 
-NeoBundle 'hynek/vim-python-pep8-indent`
+   NeoBundle 'hynek/vim-python-pep8-indent'
 
-### Notes
 
-Please note that Kirill Klenov’s [python-mode][python_mode]ships its own version
-of this bundle.  Therefore, if you want to use this version specifically, 
-you’ll have to disable python-mode’s using ::
+Notes
+-----
+
+Please note that Kirill Klenov’s python-mode_ ships its own version of this bundle.
+Therefore, if you want to use this version specifically, you’ll have to disable python-mode’s using:
+
+.. code-block:: vim
+
+   let g:pymode_indent = 0
+
+
+License and Authorship
+----------------------
+
+This script is based on one from vim’s official `script repo`_  that was *not* originally written by me.
+Unfortunately the indentation was off by one character in one case and hasn’t been updated since 2005.
+
+Even more unfortunately, I wasn’t able to reach any of the original authors/maintainers:
+**David Bustos** and **Eric Mc Sween**.
+
+So I fixed the annoyance it with the help of `Steve Losh`_ and am putting it out here so you don’t have to patch the original yourself.
+The original patch is still available here_.
+
+I’d like to thank the original authors here for their work and release it hereby to the *Public Domain* (using the CC0 licence) since I hope that would be in their spirit.
+If anyone with a say in this objects, please let me_ know immediately.
+Also, if someone is in contact with one of them, I would appreciate being introduced.
+
+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.
 
-let g:pymode_indent = 0
 
 .. _vim: http://www.vim.org/
 .. _PEP8: http://www.python.org/dev/peps/pep-0008/
@@ -76,3 +94,4 @@ let g:pymode_indent = 0
 .. _python-mode: https://github.com/klen/python-mode
 .. _`Vimscript`: http://learnvimscriptthehardway.stevelosh.com/
 .. _vundle: https://github.com/gmarik/Vundle.vim
+.. _me: https://hynek.me/