VimPlug/python-syntax
1
0
Fork 0
mirror of https://github.com/vim-python/python-syntax.git synced 2025-12-10 22:51:54 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
nfnty
2017-02-16 20:37:38 +01:00
parent 80da95bd41
commit 624b675621
2 changed files with 122 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
README.rst
View File

@@ -3,142 +3,105 @@ Python syntax highlighting script for Vim
.. contents:: .. contents::
About This is an enhanced version of the original Python syntax highlighting script. Based on
----- ``python.vim`` from Vim 6.1 distribution by Neil Schemenauer.
Enhanced version of the original Python syntax highlighting script. Based on
``python.vim`` from Vim 6.1 distribution by Neil Schemenauer (nas at python dot
ca). Check also `python.vim page on vim.org
<http://www.vim.org/scripts/script.php?script_id=790>`_.
Please report bugs and feature requests to our issue tracker over at:
https://github.com/vim-python/python-syntax/issues
Features Features
-------- --------
Changes from the original ``python.vim`` are:
- Added support for Python 3 syntax highlighting - Added support for Python 3 syntax highlighting
- Added ``:Python2Syntax`` and ``:Python3Syntax`` commands which allow to - Added commands ``Python2Syntax`` and ``Python3Syntax`` commands which allow to switch
switch between Python 2 and Python 3 syntaxes respectively without between Python 2 and Python 3 syntaxes respectively without reloads/restarts
reloads/restarts - Updated string highlighting
- Updated strings highlighting
- Enhanced special symbols highlighting inside strings - Enhanced special symbols highlighting inside strings
- Enhanced highlighting of numeric constants - Enhanced highlighting of numeric constants
- Added optional highlighting for %-formatting inside strings - Added optional highlighting for %-formatting inside strings
- Added highlighting for magic comments: source code encoding and #! - Added highlighting for magic comments: source code encoding and #! (executable) strings
(executable) strings
- Added highlighting for new exceptions and builtins - Added highlighting for new exceptions and builtins
- Added highlighting for doctests - Added highlighting for doctests
- Added highlighting for new ``@decorator`` syntax introduced in Python 2.4a2 - Added highlighting for new ``@decorator`` syntax introduced in Python 2.4a2
- Added highlighting for the following errors: - Added highlighting for the following errors:
- Invalid symbols in source file
- Mixing spaces and tabs
- Invalid numeric constants
- Invalid %-formatting inside strings
- Invalid variable names
- Trailing spaces (triggered by the ``python_highlight_space_errors`` option)
- invalid symbols in source file Folding is done by the plugin `SimpylFold <https://github.com/tmhedberg/SimpylFold>`_.
- mixing spaces and tabs
- invalid numeric constants
- invalid %-formatting inside strings
- invalid variable names
- trailing spaces (triggered by the ``python_highlight_space_errors`` option)
Some of these features was later backported into the original ``python.vim``.
Folding is done by the plugin `SimpylFold <https://github.com/tmhedberg/SimpylFold>`_
How to install How to install
-------------- --------------
The easiest installation method is to place `syntax/python.vim Use one of the following plugin managers:
<https://github.com/vim-python/python-syntax/blob/master/syntax/python.vim>`_ script
into your ``~/.vim/syntax/`` directory.
You can also use `Pathogen <https://github.com/tpope/vim-pathogen>`_ or `Vundle - `dein <https://github.com/Shougo/dein.vim>`_
<https://github.com/gmarik/vundle>`_ plugin managers in which case you can - `vim-plug <https://github.com/junegunn/vim-plug>`_
install the whole `repository - `vundle <https://github.com/VundleVim/Vundle.vim>`_
<https://github.com/vim-python/python-syntax>`_ into the corresponding plugins - `pathogen <https://github.com/tpope/vim-pathogen>`_
directory.
Or you can just manually place `syntax/python.vim
<https://github.com/vim-python/python-syntax/blob/master/syntax/python.vim>`_
into ``~/.config/nvim/syntax/`` or ``~/.vim/syntax/``.
Script options Script options
-------------- --------------
There are two commands to enable or disable an option: Enable option with::
``:let OPTION_NAME = 1`` let OPTION_NAME = 1
Enable option
``:let OPTION_NAME = 0`` Disable option with::
Disable option
let OPTION_NAME = 0
For example to enable all syntax highlighting features you can place the For example to enable all syntax highlighting features you can place the
following command in your ``~/.vimrc`` script:: following command in your ``~/.config/nvim/init.vim`` or ``~/.vimrc`` script::
let python_highlight_all = 1 let g:python_highlight_all = 1
Option and commands to select Python version Options and commands to select Python version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``python_version_2`` ``g:python_version_2`` or ``b:python_version_2``
Enable highlighting for Python 2 (Python 3 highlighting is enabled by Enable highlighting for Python 2 (Python 3 highlighting is enabled by
default). Also can be set as a local to buffer ``b:python_version_2`` default).
variable.
The following local to buffer commands can be used to switch between two The following commands can be used to switch between modes:
highlighting modes:
``:Python2Syntax`` ``Python2Syntax``
Switch to Python 2 highlighting mode Switch to Python 2
``:Python3Syntax`` ``Python3Syntax``
Switch to Python 3 highlighting mode Switch to Python 3
Options used by the script Other options
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~
``python_highlight_builtins`` ``g:python_highlight_builtins``
Highlight builtin functions and objects Highlight builtin functions and objects
``python_highlight_builtin_objs`` ``g:python_highlight_builtin_objs``
Highlight builtin objects only Highlight builtin objects only
``python_highlight_builtin_funcs`` ``g:python_highlight_builtin_funcs``
Highlight builtin functions only Highlight builtin functions only
``python_highlight_exceptions`` ``g:python_highlight_exceptions``
Highlight standard exceptions Highlight standard exceptions
``python_highlight_string_formatting`` ``g:python_highlight_string_formatting``
Highlight ``%`` string formatting Highlight ``%`` string formatting
``python_highlight_string_format`` ``g:python_highlight_string_format``
Highlight syntax of ``str.format`` syntax Highlight syntax of ``str.format`` syntax
``python_highlight_string_templates`` ``g:python_highlight_string_templates``
Highlight syntax of ``string.Template`` Highlight syntax of ``string.Template``
``python_highlight_indent_errors`` ``g:python_highlight_indent_errors``
Highlight indentation errors Highlight indentation errors
``python_highlight_space_errors`` ``g:python_highlight_space_errors``
Highlight trailing spaces Highlight trailing spaces
``python_highlight_doctests`` ``g:python_highlight_doctests``
Highlight doc-tests Highlight doc-tests
``python_print_as_function`` ``g:python_print_as_function``
Highlight ``print`` statement as function for Python 2 Highlight ``print`` statement as function for Python 2
``python_highlight_file_headers_as_comments`` ``g:python_highlight_file_headers_as_comments``
Highlight shebang and coding headers as comments Highlight shebang and coding headers as comments
``python_highlight_all`` ``g:python_highlight_all``
Enable all the options above. *NOTE: This option don't override any Enable all the options above - *NOTE: Doesn't override any previously set options*
previously set options* ``g:python_slow_sync``
``python_slow_sync`` Disable for slow machines
Can be set to 0 for slow machines
Contributors
------------
List of the contributors in alphabetical order:
- `Andrea Riciputi <https://github.com/mrrech>`_
- Anton Butanaev
- `Antony Lee <https://github.com/anntzer>`_
- Caleb Adamantine
- `David Briscoe <https://github.com/idbrii>`_
- `Elizabeth Myers <https://github.com/Elizafox>`_
- `Ihor Gorobets <https://github.com/iho>`_
- `Jeroen Ruigrok van der Werven <https://github.com/ashemedai>`_
- `John Eikenberry <https://github.com/eikenb>`_
- `Joongi Kim <https://github.com/achimnol>`_
- `Marc Weber <https://github.com/MarcWeber>`_
- `Pedro Algarvio <https://github.com/s0undt3ch>`_
- `Victor Salgado <https://github.com/mcsalgado>`_
- `Will Gray <https://github.com/graywh>`_
- `Yuri Habrusiev <https://github.com/yuriihabrusiev>`_

106
doc/python-syntax.txt
View File

@@ -1,65 +1,63 @@
PYTHON *python.vim* *ft-python-syntax* *python-syntax* *ft-python-syntax* *python.vim*
There are two commands to enable or disable an option for python.vim ===============================================================================
Configuration *python-syntax-configuration*
Enable option: > Enable option with: >
:let option_name = 1
let OPTION_NAME = 1
< <
Disable option: > Disable option with: >
:let option_name = 0
let OPTION_NAME = 0
< <
For example to enable all syntax highlighting features you can place the For example to enable all syntax highlighting features you can place the
following command in your `~/.vimrc` script: > following command in your `~/.config/nvim/init.vim` or `~/.vimrc` script: >
let python_highlight_all = 1 let g:python_highlight_all = 1
< <
Option and commands to select Python version: > -------------------------------------------------------------------------------
Options and commands to select Python version *python-syntax-version*
:let python_version_2 = 1 `g:python_version_2` or `b:python_version_2`
< Enable highlighting for Python 2 (Python 3 highlighting is enabled by
Enable highlighting for Python 2 (Python 3 highlighting is enabled by default).
default). Also can be set as a local to buffer `b:python_version_2`
variable.
The following local to buffer commands can be used to switch between two The following commands can be used to switch between modes:
highlighting modes:
Switch to Python 2 highlighting mode > `Python2Syntax`
:Python2Syntax Switch to Python 2
< `Python3Syntax`
Switch to Python 3 highlighting mode > Switch to Python 3
:Python3Syntax
<
Options used by the script
Highlight builtin functions and objects > -------------------------------------------------------------------------------
:let python_highlight_builtins = 1 Options *python-syntax-options*
< Highlight builtin objects only >
:let python_highlight_builtin_objs = 1 `g:python_highlight_builtins`
< Highlight builtin functions only > Highlight builtin functions and objects
:let python_highlight_builtin_funcs = 1 `g:python_highlight_builtin_objs`
< Highlight standard exceptions > Highlight builtin objects only
:let python_highlight_exceptions = 1 `g:python_highlight_builtin_funcs`
< Highlight `%` string formatting > Highlight builtin functions only
:let python_highlight_string_formatting = 1 `g:python_highlight_exceptions`
< Highlight syntax of `str.format` syntax > Highlight standard exceptions
:let python_highlight_string_format = 1 `g:python_highlight_string_formatting`
< Highlight syntax of `string.Template` > Highlight `%` string formatting
:let python_highlight_string_templates = 1 `g:python_highlight_string_format`
< Highlight indentation errors > Highlight syntax of `str.format` syntax
:let python_highlight_indent_errors = 1 `g:python_highlight_string_templates`
< Highlight trailing spaces > Highlight syntax of `string.Template`
:let python_highlight_space_errors = 1 `g:python_highlight_indent_errors`
< Highlight doc-tests > Highlight indentation errors
:let python_highlight_doctests = 1 `g:python_highlight_space_errors`
< Highlight `print` statement as function for Python 2 > Highlight trailing spaces
:let python_print_as_function = 1 `g:python_highlight_doctests`
< Highlight shebang and coding headers as comments > Highlight doc-tests
:let python_highlight_file_headers_as_comments = 1 `g:python_print_as_function`
< Enable all the options above. NOTE: This option don't override any Highlight `print` statement as function for Python 2
previously set options > `g:python_highlight_file_headers_as_comments`
:let python_highlight_all = 1 Highlight shebang and coding headers as comments
< Can be set to 0 for slow machines > `g:python_highlight_all`
:let python_slow_sync = 1 Enable all the options above - NOTE: Doesn't override any previously set options
< `g:python_slow_sync`
vim:tw=78:sw=4:ts=8:ft=help:norl: Disable for slow machines