diff --git a/docs/CONTRIBUTING.org b/docs/CONTRIBUTING.org index c754248..17d9e79 100644 --- a/docs/CONTRIBUTING.org +++ b/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 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..9210c60 --- /dev/null +++ b/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 diff --git a/docs/crafted-docs.el b/docs/crafted-docs.el new file mode 100644 index 0000000..239b354 --- /dev/null +++ b/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