[craftedv2beta] New tooling for exporting info documentation

docs/CONTRIBUTING.org

@@ -1,18 +1,52 @@
 * Contributing documentation
 
-  The documentation provided here is written in Org mode files. The
-  primary file is the =crafted-emacs.org= file. Each module has it's
-  own Org file as well, but each is included in the primary file.
+The documentation provided here is written in Org mode files. The
+primary file is the =crafted-emacs.org= file. Each module has it's
+own Org file as well, but each is included in the primary file.
 
-  To export the org file to an info file, run the following command:
-  =M-x org-texinfo-export-to-info RET=. To use the org export
-  interface to reach this function, make sure to first run:
+The =crafted-docs.el= file contains useful tools for working with the docs.
+To ensure the export is reproducible and independent from your Emacs
+configuration, there are two ways of exporting a clean info file.
 
-  #+begin_src emacs-lisp
-    (require 'ox-texinfo)
-  #+end_src
+Note that it is discouraged to run =M-x org-texinfo-export-to-info RET=
+or using =org-export-dispatch= directly.
+This is because it can introduce unnecessary diffs depending on certain
+Emacs configuration settings.
 
-  Then you can use =C-c C-e i= to export to info.
+** Interactively from Emacs
+
+Requirements:
+- =emacs= in your =$PATH=
+
+Evaluating this block will load the =crafted-docs.el= file into your Emacs:
+
+#+begin_src emacs-lisp
+(load (expand-file-name "crafted-docs.el"))
+#+end_src
+
+Afterwards, the info file can be exported by running
+=M-x crafted-docs-export RET=.
+
+If you're using Crafted Emacs and develop inside the repository you cloned,
+you can set =crafted-docs-export-use-crafted-emacs-home= to =t= to utilize the
+=crafted-emacs-home= path to auto-find the documentation when running
+=M-x crafted-docs-export RET=.
+
+** Using ~make~
+
+Requirements:
+- =emacs= in your =$PATH=
+- =make= in your =$PATH=
+
+If you're familiar with =make= and already have a workflow using for example
+the =compile= command in Emacs, you can use it in the =docs/= directory:
+
+#+begin_src shell
+make docs
+#+end_src
+
+Running =make docs= will automatically build the =crafted-emacs.info= file
+unless the info file is already up-to-date.
 
 * Documenting a Crafted Emacs module
 

docs/Makefile

@@ -0,0 +1,7 @@
+
+ORG_FILES=$(wildcard crafted-*.org) getting-started-guide.org mit-license.org
+
+docs: crafted-emacs.info
+
+crafted-emacs.info: $(ORG_FILES)
+	emacs -Q --script crafted-docs.el --funcall crafted-docs-export-info

docs/crafted-docs.el

@@ -0,0 +1,98 @@
+;;; crafted-docs.el --- Tooling for crafted-emacs documentation -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2023
+;; SPDX-License-Identifier: MIT
+
+;; Author: System Crafters Community
+
+;;; Commentary:
+
+;; This file is intended for working on contributions to
+;; Crafted Emacs documentation.
+
+;; The file can be loaded to expose interactive functions in Emacs:
+;; (load "[/path/to/crafted-emacs]/docs/crafted-docs.el")
+
+;; If you use crafted-emacs, you can evaluate this form directly:
+;; (load (expand-file-name "docs/crafted-docs.el" crafted-emacs-home))
+
+;; EXPORT INFO FILE
+;; The info file is best exported from a clean Emacs session.
+;; This can be done from the command-line or from within Emacs.
+
+;; Exporting from the command-line can be accomplished by running `make'.
+;; The Makefile will only generate the info file if any of the org files changed.
+;; Alternatively, if you don't want to use `make',
+;; you can run the command manually (assuming you're in docs/):
+;; emacs -Q --script crafted-docs.el -f crafted-docs-export-info
+
+;;; Code:
+
+(require 'ox-texinfo)
+
+;;; Info file export
+(defun crafted-docs-export-info ()
+  "Export crafted-emacs.info file from crafted-emacs.org in the current directory.
+Remove intermediate texi file (generated by texinfo)."
+  (with-current-buffer (find-file "./crafted-emacs.org")
+    (org-texinfo-export-to-info))
+  (delete-file "./crafted-emacs.texi")
+  (message "Generated crafted-emacs.info file"))
+
+(defvar crafted-docs-export-use-crafted-emacs-home nil
+  "If set non-nil, search in the directory specified by `crafted-emacs-home'
+for the documentation directory when running `crafted-docs-export'.")
+
+(defun crafted-docs-export--sentinel (proc event)
+  "Sentinel for `crafted-docs-export' providing customized message feedback.
+PROC and EVENT are passed by `make-process' where PROC is unused here and
+EVENT contains the standard event-text."
+  (cond ((string-match-p "finished" event)
+         (message "Crafted Emacs: docs export finished"))
+        ((string-match-p "exited.*" event)
+         (message "Crafted Emacs Docs export %s. See *crafted-docs-export* buffer for more information"
+                  event))))
+
+(defun crafted-docs-export (&optional crafted-docs-directory)
+  "Export crafted-emacs.info file in a separate Emacs session.
+
+Unless passed as CRAFTED-DOCS-DIRECTORY,
+attempt to find the Crafted Emacs docs directory.
+The current directory is checked first.
+If `crafted-docs-export-use-crafted-emacs-home' is non-nil and
+`crafted-emacs-home' is an existing directory, use the `docs' sub-directory there.
+If none of the above produce a directory, prompt
+the user to specify the docs directory using `read-directory-name'.
+
+This does not utilize make, instead running Emacs as a separate process directly.
+If you want to use the Makefile, look at the `compile' command.
+
+Export output is written to the *crafted-docs-export* buffer."
+  (interactive
+   (list
+    (cond ((file-exists-p "./crafted-docs.el") ".")
+          ((and crafted-docs-export-use-crafted-emacs-home
+                (boundp 'crafted-emacs-home)
+                (file-directory-p crafted-emacs-home))
+           (expand-file-name "docs/" crafted-emacs-home))
+          (t (read-directory-name "Crafted Emacs docs-directory: ")))))
+
+  (unless (executable-find "emacs")
+    (user-error "Emacs is not in PATH"))
+
+  (let ((docs-directory (expand-file-name crafted-docs-directory))
+        (docs-script (expand-file-name "crafted-docs.el"
+                                       crafted-docs-directory)))
+    (if (file-exists-p docs-script)
+        (make-process :name "crafted-docs-export"
+                      :buffer "*crafted-docs-export*"
+                      :command (list "emacs"
+                                     "-Q" "--script" "crafted-docs.el"
+                                     "--chdir" docs-directory
+                                     "--funcall" "crafted-docs-export-info")
+                      :sentinel #'crafted-docs-export--sentinel)
+      (user-error "Directory %s is not the Crafted Emacs docs directory"
+                  docs-directory))))
+
+(provide 'crafted-docs)
+;;; crafted-docs.el ends here