My .vimrc usually starts out with this. Syntax highlighting is super, and my terminals always have a black background. The modeline option enables me and others to set certain options for certain files only. Like: {# vim: syntax=htmldjango: #} to mark a .html file as using the django html syntax instead of regular html syntax. See also my Inserting vim modelines tip.

syn on
set bg=dark
set modeline

Second, since I develop a lot in Python, I enable the vim-flake8 python source code checker plugin:

$ sudo pip install flake8
$ mkdir -p ~/.vim/ftplugin
$ wget -O ~/.vim/ftplugin/ \
    https://github.com/nvie/vim-flake8/raw/master/ftplugin/python_flake8.vim

This also requires the following additions to your .vimrc:

" Enable python_flake8 checker
filetype plugin indent on
" HtmlIndent() always works against me in 2013, disable it
autocmd BufEnter *html set indentexpr=

Now you can open any Python .py file and do basic checks on it by pressing <F7>. In the background it runs flake8 which will show you a list of potential problems or code style violations.

Beware! Pressing F7 will save the open file!

Next, we can optionally set global flake8 defaults, like this:

" Not sure about these defaults anymore. They worked for me when moving
" to the PEP checker initially. I'll probably go full PEP8 in a while.
let g:flake8_ignore="E125,E128"

And then we set project-specific defaults. (My projects directory name srcelf is a contraction of src and self to distinguish itself from the ~/src directory where apt-get source'd (and similar) items go.)

" Bosso-project
autocmd BufEnter /home/walter/srcelf/bosso/*py set ts=8 sw=4 sts=4 et ai tw=99|let g:flake8_max_line_length=99
autocmd BufEnter /home/walter/srcelf/bosso/*html set ts=8 sw=4 sts=4 et ai nowrap
autocmd BufEnter /home/walter/srcelf/bosso/*xml set ts=8 sw=4 sts=4 et ai

" Another-project
" ...

Notice how we increase the textwidth to 99 characters for both vim and the flake8 checker.

For Django projects, 79 characters is generally too little. Some projects favor 119 characters. I try to go with 99 whenever possible. It makes code fit on half of my screen and make side-by-side diffs nice and readable.

Alright, we're almost there. Finally on to the topic that I was planning to write about: paragraph reformatting and textwidth.

Paragraph reformatting

You probably know what you can reformat a paragraph in vim with gq. You select a portion using either CTRL-V and arrows and then gq or you select the whole file by jumping to top, doing gq and jumping to the end: gggqG

Unfortunately that will reformat to the current textwidth (99 or 119) which is not recommended. PEP8 says 72 characters. And that is the absolute maximum for longer bits of text.

(Read the column mode simetimes better than widespan article on the c2 Content Creation Wiki for why. It graphically shows how humans are better at reading (or glancing through) column layout than wide pages.)

The fix: tell vim to temporarily switch to 72 character textwidth when doing a reformat. Like this:

vnoremap gq <Esc>:let tw=&tw<CR>:set tw=72<CR>gvgq:let &tw=tw<CR>

Excellent! This makes the CTRL-V-arrows-gq method use a 72 characters limit. Precisely what we need to reformat python docstrings.

On the fly formatting

P.S. Vim can also do reformatting on the fly. That can be useful when writing .txt documentation. Add this to the tail of your document. The ugly looking flp= describes what bullet lists are.

-- vim: set tw=71 fo=twan flp=^\\s*\\(\\d\\+\\.\\|[*-]\\)\\s* ai nosi:
-- vim: set ts=8 sw=2 sts=2 ei:
-- see :help fo-table

Completely unrelated sudo-write trick

P.P.S. Since we're doing command (re)mapping here, we might as well add this useful one. Stolen from Nathan Long's answer to how does the vim write with sudo trick work.

" Allow saving of files as sudo when I forgot to start vim using sudo.
cmap w!! w !sudo tee % >/dev/null

python documentation vim