refactor(file-templates): doom readme templates

Including readme template for categories.

modules/editor/file-templates/autoload.el

@@ -96,6 +96,14 @@ evil is loaded and enabled)."
              (file-relative-name path doom-private-dir))
             ((abbreviate-file-name path))))))
 
+;;;###autoload
+(defun +file-templates-module-for-path (&optional path)
+  "Generate a title for a doom module's readme at PATH."
+  (let ((m (doom-module-from-path (or path (buffer-file-name)))))
+    (if (eq (cdr m) 'README.org)
+        (symbol-name (car m))
+      (format "%s %s" (car m) (cdr m)))))
+
 
 ;;
 ;;; Commands
@@ -133,3 +141,20 @@ for it. This is used for testing."
                      :key #'yas--template-key :test #'equal))
         (message "Found %s" (cons pred plist))
       (message "Found rule, but can't find associated snippet: %s" (cons pred plist)))))
+
+
+;;
+;;; Trigger functions
+
+(defun +file-templates-insert-doom-docs-fn ()
+  "Expand one of Doom's README templates depending."
+  (+file-templates--expand
+   t :trigger
+   (let ((path (file-truename (buffer-file-name))))
+     (cond ((string-match-p "/modules/[^/]+/README\\.org$" path)
+            "__doom-category-readme")
+           ((string-match-p "/modules/[^/]+/[^/]+/README\\.org$" path)
+            "__doom-readme")
+           ((file-in-directory-p path doom-docs-dir)
+            "__doom-docs")
+           ("__")))))

modules/editor/file-templates/config.el

@@ -72,9 +72,8 @@ don't have a :trigger property in `+file-templates-alist'.")
     ("/shell\\.nix$" :trigger "__shell.nix")
     (nix-mode)
     ;; Org
-    ("/README\\.org$"
-     :when +file-templates-in-emacs-dirs-p
-     :trigger "__doom-readme"
+    (doom-docs-org-mode
+     :trigger +file-templates-insert-doom-docs-fn
      :mode org-mode)
     (org-journal-mode :ignore t)
     (org-mode)

modules/editor/file-templates/templates/org-mode/__doom-category-readme

@@ -0,0 +1,12 @@
+# -*- mode: snippet -*-
+# name: Doom category readme
+# --
+← [[doom-module-index:][Back to module index]]                         ↖ [[doom-module-source:lang][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
+--------------------------------------------------------------------------------
+#+TITLE:   `(+file-templates-module-for-path)`
+#+CREATED: `(format-time-string "%B %d, %Y")`
+#+SINCE:   `(car (split-string doom-version "-"))`
+$0
+* Description
+Replace this with a description of what modules in this category are for,
+including any important information (like load order constraints).

modules/editor/file-templates/templates/org-mode/__doom-docs

@@ -0,0 +1,9 @@
+# -*- mode: snippet -*-
+# name: Doom documentation
+# --
+← [[doom-index:][Back to index]]                                ↖ [[doom-docs-source:faq.org][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help:][Help]]
+--------------------------------------------------------------------------------
+#+TITLE:     ${1:Title}
+#+SUBTITLE:  ${2:Subtitle}
+
+$0

modules/editor/file-templates/templates/org-mode/__doom-readme

@@ -1,70 +1,196 @@
 # -*- mode: snippet -*-
 # name: Doom module readme                                             
 # --
-#+TITLE:   ${1:`(if (string-match "modules/\\([^/]+\\)/\\([^/]+\\)/.+" buffer-file-name)
-                    (format "%s/%s"
-                            (match-string 1 buffer-file-name)
-                            (match-string 2 buffer-file-name))
-                  "")`}
-#+DATE:    `(format (format-time-string "%B %%s, %Y") (string-to-number (format-time-string "%d")))`
-#+SINCE:   ${2:<replace with next tagged release version>}
-#+STARTUP: inlineimages nofold
+← [[doom-module-index:][Back to module index]]               ↙ [[doom-module-issues:::lang rust][Issues]]  ↖ [[doom-module-source:lang/rust][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
+--------------------------------------------------------------------------------
+#+TITLE:     `(+file-templates-module-for-path)`
+#+SUBTITLE:  <A one-line quip about this module to display in init.example.el>
+#+CREATED:   `(format-time-string "%B %d, %Y")`
+#+SINCE:     `(car (split-string doom-version "-"))` (#COMMIT-OR-PR-REF)
 
-* Table of Contents :TOC_3:noexport:
+* Description :unfold:
+$0Replace this with a short (1-2 sentence) description of what this module does.
+This is displayed in the module index.
 
-* Description
-${3:# A summary of what this module does.}
-
-+ If possible, include a brief list of feature highlights here
-+ Like code completion, syntax checking or available snippets
-+ Include links to packages & external things where possible
+Then a longer, multiple paragraph description goes here, which should explain
+the purpose of the module and the features/technology(ies) it provides.
 
 ** Maintainers
-+ @username_linked_to_gihub (Author)
-+ @username_linked_to_gihub
-+ @username_linked_to_gihub
+- [[doom-user:][@github_username]]
+- [[doom-user:][@github_username]]
+- [[doom-user:][@github_username]]
 
-# If this module has no maintainers, then...
-This module has no dedicated maintainers.
+[[doom-contrib-maintainer:][Become a maintainer?]]
 
-** Module Flags
-+ =+flag1= A short description of what this flag does and what it might need
-  when enabled.
-+ =+flag2= A short description of what this flag does and what it might need
-  when enabled.
-+ =+flag3= A short description of what this flag does and what it might need
-  when enabled.
+# If a module has no maintainers and can't be casually maintained by Henrik
+# alone, use:
+*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
+
+# Otherwise, use:
+/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
+
+** Module flags
+# Flags should be in alphanumerical order.
+- +bar ::
+  A short description of what this flag does and what it might need when
+  enabled.
+- +childframe ::
+  Display X in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an overlay or tooltip. *Requires GUI
+  Emacs.*
+- +lsp ::
+  Enable LSP support for ~X-mode~. Requires [[doom-module:][:tools lsp]] and a
+  langserver (supports A, B, and C).
 
 # If this module has no flags, then...
-This module provides no flags.
+/This module has no flags./
 
-** Plugins
-# A list of linked plugins
-+ [[https://orgmode.org/][org-plus-contrib]]
-+ [[https://github.com/sabof/org-bullets][org-bullets]]
-+ [[https://github.com/TobiasZawada/org-yt][org-yt]]
-+ [[https://github.com/sebastiencs/company-box][company-box]]* (=+childframe=)
-+ =:lang crystal=
-  + [[https://github.com/brantou/ob-crystal][ob-crystal]]
-+ =:lang go=
-  + [[https://github.com/pope/ob-go][ob-go]]
-+ =+present=
-  + [[https://github.com/anler/centered-window-mode][centered-window]]
-  + [[https://github.com/takaxp/org-tree-slide][org-tree-slide]]
-  + [[https://gitlab.com/oer/org-re-reveal][org-re-reveal]]
+# If this module has flags but you can't document them now, add a TODO to the
+# heading and use:
+#+begin_quote
+ 🔨 This module has flags, but they aren't documented yet. [[doom-contrib-module:][Document them?]]
+#+end_quote
+
+** Packages
+- [[doom-package:][org]]
+- [[doom-package:][org-contrib]] if [[doom-module:][+contrib]]
+- [[doom-package:][org-bullets]] unless  [[doom-module:][+bullets]]
+- if [[doom-module:][+present]]
+  - [[doom-package:][centered-window]]
+  - [[doom-package:][org-tree-slide]]
+  - [[doom-package:][org-re-reveal]]
+
+# If this module installs no packages, then...
+/This module doesn't install any packages./
+
+# If this module installs packages, but you can't document them now, add a TODO
+# to the heading and use:
+#+begin_quote
+ 🔨 This module installs packages, but they aren't documented yet. [[doom-contrib-module:][Document
+    them?]]
+#+end_quote
 
 ** Hacks
-# A list of internal modifications to included packages; omit if unneeded
+# Place a list of internal (and potentially unexpected) modifications to
+# included packages:
+- Fixed X which should help you do Y
+- Advised Z to work harder, better, faster, stronger.
+- Tricked the hobbitses into giving me the precious.
 
-* Prerequisites
-This module has no prerequisites.
+# If there aren't any hacks, use:
+/No hacks documented for this module./
 
-* Features
-# An in-depth list of features, how to use them, and their dependencies.
+# If this module contains hacks, but you can't document them now, add a TODO to
+# the heading and use:
+#+begin_quote
+ 🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
+#+end_quote
 
-* Configuration
-# How to configure this module, including common problems and how to address them.
+** TODO Changelog
+# Do not edit this by hand. Your commits are your changelog. Commits that
+# shouldn't show up should use the 'Amend: ...' trailer (see
+# https://docs.doomemacs.org/-/git-conventions for details).
+#
+# ALSO: Version headings should be linked to the respective heading in
+# docs/changelog.org.
+** [[doom-release:v21.12.0][v21.12.0]] [2021-12-30]
+*** [[doom-commit:a1b2c3d4][commit SUBJECT linked to github commit]]
+commit BODY
+*** [[doom-commit:a1b2c3d4][commit SUBJECT linked to github commit]]
+commit BODY
+*** [[doom-commit:a1b2c3d4][commit SUBJECT linked to github commit]]
+commit BODY
+
+# If no changelog is available, use:
+# This section will be machine generated. Don't edit it by hand.
+/This module does not have a changelog yet./
+
+* Installation
+# This section should describe, in-depth, how to set up this module and its
+# dependencies, starting with this line:
+[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
+# ...Then list its external requirements, if any.
+This module requires:
+- ...
+- ...
+- ...
+# And finally, go into detail about how to install them.
+
+# If there are no external requirements, use:
+/This module has no external requirements./
+
+# If there are prerequisites but you can't document them yet, add TODO to the
+# heading and use:
+#+begin_quote
+ 🔨 /No installation steps have been documented./ [[doom-contrib-module:][Document them?]]
+#+end_quote
+
+* Usage
+# Walk the user through how this module is used.
+
+# If this is left empty, add TODO to the heading and use:
+#+begin_quote
+ 🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
+#+end_quote
+
+# If this section has incomplete content, add TODO to the heading and use:
+#+begin_quote
+ 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
+#+end_quote
+
+* TODO Configuration
+# Walk the user through how to configure this module, including any variables it
+# exposes or user-facing configuration API.
+
+# If this is left empty, add TODO to the heading and use:
+#+begin_quote
+ 🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
+#+end_quote
+
+# If this section has incomplete content, add TODO to the heading and use:
+#+begin_quote
+ 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
+#+end_quote
 
 * Troubleshooting
-# Common issues and their solution, or places to look for help.
-$0
+# List common issues and any workarounds/solutions, or link to external resources. 
+[[doom-report:][Report an issue?]]
+
+** Common issue
+Solution.
+** Common issue
+Solution.
+** Common issue
+Solution.
+
+# If this is left empty, use:
+/There are no known problems with this module./ [[doom-report:][Report one?]]
+
+* Frequently asked questions
+[[doom-suggest-faq:][Ask a question?]]
+
+# This is for adoption, design, or niche questions. More general
+# usage/configuration matters should be covered in the sections above.
+** Question
+Answer
+** Question
+Answer
+** Question
+Answer
+
+# If no questions are available, use
+/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
+
+* TODO Appendix
+# A glossary of important major modes, minor modes, commands, functions, faces,
+# and variables that this module exposes. It doesn't have to be exhaustive and
+# should omit explanation/documentation.
+
+# If this is left empty, add TODO to the heading and use:
+#+begin_quote
+ 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
+#+end_quote
+
+# If this section has incomplete content, add TODO to the heading and use:
+#+begin_quote
+ 🔨 /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]]
+#+end_quote

modules/lang/emacs-lisp/autoload.el

@@ -95,7 +95,7 @@ if it's callable, `apropos' otherwise."
              (with-demoted-errors "%s"
                (re-search-forward
                 (if (caddr module)
-                    "\\* Module Flags$"
+                    "\\* Module flags$"
                   "\\* Description$"))
                (when (caddr module)
                  (re-search-forward (format "=\\%s=" (caddr module))

modules/lang/org/autoload/org-link.el

@@ -195,9 +195,9 @@ exist, and `org-link' otherwise."
           (user-error "Can't find Doom module '%s'" link))))
     (when flag
       (goto-char (point-min))
-      (and (re-search-forward "^\\*+ \\(?:TODO \\)?Module Flags")
-           (re-search-forward (format "^\\s-*- %s :: "
-                                      (regexp-quote (symbol-name flag)))
+      (and (re-search-forward "^\\*+ \\(?:TODO \\)?Module flags")
+           (re-search-forward (format "^\\s-*- \\+%s ::[ \n]"
+                                      (substring (symbol-name flag) 1))
                               (save-excursion (org-get-next-sibling)
                                               (point)))
            (recenter)))))