VIM_PY3_RST                                                   *vim-py3-rst*
                                                              *vim_py3_rst*

`vim_py3_rst` Provides shortcuts and utility functions

- to run python code using Vim's `:py3`: |vim_py3|

- to edit `reStructuredText`: |vim_rst|

Note: Code to generate this doc is in `vim_py3_rst.vim`.

==============================================================================
VIM_PY3_RST                                                   *vim-py3*
                                                              *vim_py3*

These mappings apply either to the visual area (can also be within one line)
or the current line.

`<leader>jj`: evaluate and print.
              If there is a `__pyout__` buffer ...

`<leader>jw`, `:PyOut`: printing goes to that buffer.

`<leader>jk`: only evaluate

`<leader>jl`: evaluate and capture print in * register

`<leader>je`: expand bottle `SimpleTemplate`/`stpl`

`<leader>jd`: evaluate the python `doctest` in the visual range

`<leader>jt`: profile the selected code using `timeit`
              (within a `.py` file)

`<leader>jh`: print python help of word under cursor

`<leader>jc`: convert columns to lines and evaluate

`<leader>jr`: print result of each line after a comment char #

`return`, `yield`, ... are skipped, if evaluating only one line.

` >#.%,\\t` in the first line of visual determines n chars skipped at the
beginning of each line. If needed, start visual with an empty line.


==============================================================================
VIM_PY3_RST                                                   *vim-rst*
                                                              *vim_rst*

The functionality is provided by the python package `rstdoc`,
which uses `.rest` for main docs, `.rst` for included files, or templates.

See https://rstdoc.readthedocs.io/en/latest/index.html

The following system commands provided by `rstdoc` can be directly used.

`!rstdoc --stpl <foldername>`: produce sample project with `.stpl` files
`!rstdoc --rest <foldername>`: produce sample project `.rest` files
`!rstdoc`: updates `.tags` and link files files in all subdirectories.

Preview

This preview can be done either on the visual or on the whole document.
It uses `VimShowRst`, whose `outinfo` parameter specifies format and whether
`Docutils`, `Sphinx` or `Pandoc` is used (see rstdoc).
One can define one's own global `VimShowRst` python function and, e.g.,
to provide an `outfile` parameter not in the generated temporary directory.
One can also override `VimShowRstTempSrc`, to control the path below the
generated temporary directory.

`<leader>lh`, html, defaults to `Docutils`
`<leader>lx`, sphinc_html, defaults to `Sphinx`
`<leader>lt`, pdf, defaults to `Pandoc`


Tables

In Vim, visually select, then do `:'<,'> py3 Xxx(args)`):

`ListTable`: convert grid tables to list table
`ReFlow`: re-flow grid tables and paragraphs
`UnTable`: convert 2- or 3-column.list tables to paragraphs
           (1st column is ID, i.e. no blanks)
`ReTable`: transform list table to grid table

The following functions use the cursor position, not the visual.

`ReformatTable`: creates table from e.g. double space separated format
`ReflowTable`: adapts table to new first line
`ReTitle`: fixes the header underlines
`UnderLine`: add underline
`TitleLine`: add title lines

The implementation is in `rstdoc.retable`.

`<leader>etf`: format into table columns, where there are at least 2 spaces
`<leader>etr`: reformat based on the length of the first border line


Headers

Header underlines within one `.rest` must be consistent.

`<leader>hx`: with `x∈{1,..,f}`, to make header of depth `x`.
              See `title_some` in `rstdoc.retable`.

`<leader>ett` reformats the header underlining
`<leader>etu` transform to next header up
`<leader>etd` transform to next header down
`<leader>eta`: anchor for item or header line, random if on empty line
`<leader>etg`: shorter anchor


Keyword Lines

A RST comment of shape::

  .. {{{kw1,kw2,...

is seen as keyword line according ``rstdoc.dcx.rexkw``, which can be changed.
This has been generalized to other comments. See `yield_with_kw()` in
https://github.com/rpuntaie/rstdoc/blob/master/rstdoc/dcx.py.

Such lines can be searched with

`:Ck`: list keyword lines of current file, containing args
`:CK`: list keyword lines in all rst and py files under current dir,
       containing args

If no args are given, then the words in the current line are used as args.

`:Cp`: go to the previous keyword line
`:Cn`: go to the next keyword line


 vim:tw=78:ts=8:noet:ft=help:norl: