[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.

layers/+tools/sphinx/README.org

@@ -31,21 +31,23 @@ in this file.
 ** 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.
+A parent directory is needed for all your Sphinx project builds:
 
 #+BEGIN_SRC emacs-lisp
   (sphinx :variables
-          rst-sphinx-target-parent "/your/path/of/build/")
+          rst-sphinx-target-parent "~/MyProjects/")
 #+END_SRC
 
-Set a directory in the parent directory for each Sphinx project.
+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 "/your/path/of/build/"
+          rst-sphinx-target-parent "~/MyProjects/"
           rst-sphinx-target-projects
-          '(("project1" . (latex "folder/in/target/parent" t))
-            ("project2" . (html  "folder/in/target/parent" nil))))
+          '(("project1" . (latex "project1/_build"))
+            ("project2" . (html  "project2/_build"))))
 #+END_SRC
 
 ** Web browser

layers/+tools/sphinx/local/rst-sphinx/rst-sphinx.el

@@ -28,7 +28,7 @@ document with \\[rst-sphinx]."
 
 (defvar rst-sphinx-builder
   '((html . "html")
-    (latex . "xelatex"))
+    (latex . "latex"))
   "Table describing the builder used to compile.")
 
 (defvar rst-sphinx-source nil
@@ -75,16 +75,17 @@ document with \\[rst-sphinx]."
   "Return path to conf.py or nil if not found."
   ;; (interactive)
   (let* ((file-name "conf.py")
-        (buffer-file (buffer-file-name))
-        (dir (file-name-directory buffer-file))
-        (conf-py (concat dir file-name)))
+         (buffer-file (buffer-file-name))
+         (dir (file-name-directory buffer-file))
+         (conf-py (concat dir file-name)))
+
     ;; Move up in the dir hierarchy to find conf.py
-    (while (or (not buffer-file)
-               (not (file-exists-p conf-py)))
+    ;; Make sure to stop if root is reached
+    (while (and (not (string= dir (directory-file-name dir)))
+                (not (file-readable-p conf-py)))
       ;; Move up to the parent dir and try again.
-      (setq buffer-file (directory-file-name
-                         (file-name-directory buffer-file)))
       (setq dir (file-name-directory buffer-file))
+      (setq buffer-file (directory-file-name dir))
       (setq conf-py (concat dir file-name)))
     (if buffer-file
         conf-py
@@ -121,15 +122,11 @@ If CLEAN is non-nil then clean the project before compiling."
 (defun rst-sphinx-clean ()
   "Clean Sphinx project."
   (interactive)
-  (let* ((conf (rst-sphinx-find-conf-py-path))
-         (build (when conf (concat (file-name-directory conf)
-                                   rst-sphinx-target-parent))))
-    (if (file-exists-p build)
-        (progn
-          (delete-directory build t)
-          (message "Project cleaned successfully."))
-      (message "Cannot find build directory \"%s\"" rst-sphinx-target-parent))))
-
+  (if (rst-sphinx-set-variables)
+      (progn
+        (delete-directory rst-sphinx-target t)
+        (message "Project cleaned successfully."))
+    (message "Cannot find build directory \"%s\"" rst-sphinx-target-parent)))
 
 (defun rst-sphinx-rebuild ()
   "Clean and compile Sphinx project."