spacemacs/layers/+tools/sphinx/README.org

#+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 |
reST: Extract sphinx specific config to a stand alone sphinx layer 2017-02-02 19:55:18 +00:00			`#+TITLE: Sphinx layer`

Add more tags 2019-05-02 21:49:30 +00:00			`#+TAGS: layer\|tool`

reST: Extract sphinx specific config to a stand alone sphinx layer 2017-02-02 19:55:18 +00:00			`[[file:img/sphinx.png]]`

Switch to the new layers generator 2019-05-07 20:05:06 +00:00			`* Table of Contents :TOC_5_gh:noexport:`
update docs to the new toc-org format 2017-05-22 14:16:12 +00:00			`- [[#description][Description]]`
Fix documentation for sphinx, confluence, helm and ivy layer 2017-12-15 16:40:39 +00:00			`- [[#features][Features:]]`
update docs to the new toc-org format 2017-05-22 14:16:12 +00:00			`- [[#install][Install]]`
			`- [[#configuration][Configuration]]`
			`- [[#sphinx-target][Sphinx target]]`
			`- [[#web-browser][Web browser]]`
			`- [[#key-bindings][Key bindings]]`
reST: Extract sphinx specific config to a stand alone sphinx layer 2017-02-02 19:55:18 +00:00
			`* Description`
Fix documentation for sphinx, confluence, helm and ivy layer 2017-12-15 16:40:39 +00:00			`The layer adds support for the documentation generation system =Sphinx= to`
reST: Extract sphinx specific config to a stand alone sphinx layer 2017-02-02 19:55:18 +00:00			`the =restructuredtext= layer.`

Fix documentation for sphinx, confluence, helm and ivy layer 2017-12-15 16:40:39 +00:00			`** Features:`
			`- Support for =Sphinx= project compilation`
			`- Support for opening =Sphinx= project target`
			`- Support for opening =Sphinx= config file`

reST: Extract sphinx specific config to a stand alone sphinx layer 2017-02-02 19:55:18 +00:00			`* 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`
documentation formatting: Sun May 26 20:58:52 UTC 2019 2019-05-26 20:58:52 +00:00			`To use the layer's Sphinx feature, the following variables should be set.`
reST: Extract sphinx specific config to a stand alone sphinx layer 2017-02-02 19:55:18 +00:00
[sphinx] Restore document generation/cleaning feature and document config vars 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. 2020-02-22 10:35:59 +00:00			`A parent directory is needed for all your Sphinx project builds:`
reST: Extract sphinx specific config to a stand alone sphinx layer 2017-02-02 19:55:18 +00:00
[sphinx] Fix typo in documentation 2020-02-21 23:47:37 +00:00			`#+BEGIN_SRC emacs-lisp`
[sphinx] Improve documentation and add proper command prefixes 2020-02-21 23:45:20 +00:00			`(sphinx :variables`
[sphinx] Restore document generation/cleaning feature and document config vars 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. 2020-02-22 10:35:59 +00:00			`rst-sphinx-target-parent "~/MyProjects/")`
Reformat documentation 2018-09-19 03:54:47 +00:00			`#+END_SRC`
reST: Extract sphinx specific config to a stand alone sphinx layer 2017-02-02 19:55:18 +00:00
[sphinx] Restore document generation/cleaning feature and document config vars 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. 2020-02-22 10:35:59 +00:00			`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.`
reST: Extract sphinx specific config to a stand alone sphinx layer 2017-02-02 19:55:18 +00:00
Reformat documentation 2018-09-19 03:54:47 +00:00			`#+BEGIN_SRC emacs-lisp`
[sphinx] Improve documentation and add proper command prefixes 2020-02-21 23:45:20 +00:00			`(sphinx :variables`
[sphinx] Restore document generation/cleaning feature and document config vars 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. 2020-02-22 10:35:59 +00:00			`rst-sphinx-target-parent "~/MyProjects/"`
[sphinx] Improve documentation and add proper command prefixes 2020-02-21 23:45:20 +00:00			`rst-sphinx-target-projects`
[sphinx] Restore document generation/cleaning feature and document config vars 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. 2020-02-22 10:35:59 +00:00			`'(("project1" . (latex "project1/_build"))`
			`("project2" . (html "project2/_build"))))`
Reformat documentation 2018-09-19 03:54:47 +00:00			`#+END_SRC`
reST: Extract sphinx specific config to a stand alone sphinx layer 2017-02-02 19:55:18 +00:00
			`** 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.`

Reformat documentation 2018-09-19 03:54:47 +00:00			`#+BEGIN_SRC emacs-lisp`
[sphinx] Improve documentation and add proper command prefixes 2020-02-21 23:45:20 +00:00			`(sphinx :variables`
			`rst-slides-program "chromium")`
Reformat documentation 2018-09-19 03:54:47 +00:00			`#+END_SRC`
reST: Extract sphinx specific config to a stand alone sphinx layer 2017-02-02 19:55:18 +00:00
			`* Key bindings`

[sphinx] Improve documentation and add proper command prefixes 2020-02-21 23:45:20 +00:00			`\| 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 \|`