From 0aad1399ccae03720e9e9aff53096176c97ccf25 Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Tue, 12 Oct 2021 21:26:05 +0200 Subject: [PATCH] refactor(file-templates): doom readme templates Including readme template for categories. --- modules/editor/file-templates/autoload.el | 25 ++ modules/editor/file-templates/config.el | 5 +- .../templates/org-mode/__doom-category-readme | 12 + .../templates/org-mode/__doom-docs | 9 + .../templates/org-mode/__doom-readme | 228 ++++++++++++++---- modules/lang/emacs-lisp/autoload.el | 2 +- modules/lang/org/autoload/org-link.el | 6 +- 7 files changed, 229 insertions(+), 58 deletions(-) create mode 100644 modules/editor/file-templates/templates/org-mode/__doom-category-readme create mode 100644 modules/editor/file-templates/templates/org-mode/__doom-docs diff --git a/modules/editor/file-templates/autoload.el b/modules/editor/file-templates/autoload.el index 114507cae..c96d79beb 100644 --- a/modules/editor/file-templates/autoload.el +++ b/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") + ("__"))))) diff --git a/modules/editor/file-templates/config.el b/modules/editor/file-templates/config.el index 3de046a39..75b2b8783 100644 --- a/modules/editor/file-templates/config.el +++ b/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) diff --git a/modules/editor/file-templates/templates/org-mode/__doom-category-readme b/modules/editor/file-templates/templates/org-mode/__doom-category-readme new file mode 100644 index 000000000..cfc71a7f1 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/modules/editor/file-templates/templates/org-mode/__doom-docs b/modules/editor/file-templates/templates/org-mode/__doom-docs new file mode 100644 index 000000000..86d521121 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/modules/editor/file-templates/templates/org-mode/__doom-readme b/modules/editor/file-templates/templates/org-mode/__doom-readme index 695067459..07537c0c3 100644 --- a/modules/editor/file-templates/templates/org-mode/__doom-readme +++ b/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:} -#+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: +#+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 \ No newline at end of file +# 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 \ No newline at end of file diff --git a/modules/lang/emacs-lisp/autoload.el b/modules/lang/emacs-lisp/autoload.el index 030fc9563..9370f4b2d 100644 --- a/modules/lang/emacs-lisp/autoload.el +++ b/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)) diff --git a/modules/lang/org/autoload/org-link.el b/modules/lang/org/autoload/org-link.el index 8be27d577..56d851f2a 100644 --- a/modules/lang/org/autoload/org-link.el +++ b/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)))))