#+TITLE: reStructuredText layer

* Table of Contents                                        :TOC_4_gh:noexport:
- [[#description][Description]]
  - [[#features][Features]]
- [[#install][Install]]
- [[#configuration][Configuration]]
  - [[#sphinx-target][Sphinx target]]
  - [[#web-browser][Web browser]]
- [[#key-bindings][Key bindings]]

* Description
The layer adds ReStructuredText (ReST) support to Spacemacs and adds some
functions to =rst-mode=.

** Features
- =rst= files are supported via Emacs built-in =rst.el=.
- Lists are inserted by new functions.
- Directives can be inserted easily.
- Sphinx support.

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =restructuredtext= to the existing =dotspacemacs-configuration-layers= list
in this file.

* Configuration
** Sphinx target
To use the layer's Sphinx feature, the following variables should be set.

A parent directory is needed for all Sphinx projects' builds.

#+begin_src emacs-lisp
    (setq rst-sphinx-target-parent "/your/path/of/build/")
#+end_src

Set a directory in the parent directory for each Sphinx project.

#+begin_src emacs-lisp
    (setq rst-sphinx-target-projects
          '(("project1" . (latex "folder/in/target/parent" t))
            ("project2" . (html  "folder/in/target/parent" nil))
            ))
#+end_src

** Web browser
Set the browser for viewing the HTML page of current rst file. This one
is optional. If not set, the default browser will be used.

#+begin_src emacs-lisp
    (setq rst-slides-program "chromium")
#+end_src

* Key bindings

| Key Binding | Description                             |
|-------------+-----------------------------------------|
| ~<SPC> m c~ | compile projects                        |
| ~<SPC> m f~ | open compiled HTML page of current page |