fee257b46e
I have noticed that most commands from the sphinx layer stopped working while I was working on the restructured text layer. This commit tries to jurry rig this package back into a working state. It does not solve all issues we have in this package to do so a major rewrite would be in order. I have fixed: - An endless loop caused by a failing search for a conf.py - Fixed all compile commands - Add a more detailed description of the meaning of the necessary config variables in the doc.
71 lines
2.1 KiB
Org Mode
71 lines
2.1 KiB
Org Mode
#+TITLE: Sphinx layer
|
|
|
|
#+TAGS: layer|tool
|
|
|
|
[[file:img/sphinx.png]]
|
|
|
|
* Table of Contents :TOC_5_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 support for the documentation generation system =Sphinx= to
|
|
the =restructuredtext= layer.
|
|
|
|
** Features:
|
|
- Support for =Sphinx= project compilation
|
|
- Support for opening =Sphinx= project target
|
|
- Support for opening =Sphinx= config file
|
|
|
|
* Install
|
|
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
|
|
add =sphinx= 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 your Sphinx project builds:
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(sphinx :variables
|
|
rst-sphinx-target-parent "~/MyProjects/")
|
|
#+END_SRC
|
|
|
|
Create a directory in the parent directory for each Sphinx project.
|
|
This will be used as the project name for the layer. In addition
|
|
you need to define where the output folder should be for each project.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(sphinx :variables
|
|
rst-sphinx-target-parent "~/MyProjects/"
|
|
rst-sphinx-target-projects
|
|
'(("project1" . (latex "project1/_build"))
|
|
("project2" . (html "project2/_build"))))
|
|
#+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
|
|
(sphinx :variables
|
|
rst-slides-program "chromium")
|
|
#+END_SRC
|
|
|
|
* Key bindings
|
|
|
|
| Key binding | Description |
|
|
|-------------+-----------------------------------------|
|
|
| ~SPC m c c~ | compile projects |
|
|
| ~SPC m c C~ | clean projects |
|
|
| ~SPC m c r~ | rebuild projects |
|
|
| ~SPC m g c~ | open =conf.py= of current project |
|
|
| ~SPC m o~ | open compiled HTML page of current page |
|