merge: rewrite-docs
I've omitted docs/*.org from this merge, as there is still work left to do there, but I am pushing the module docs early so folks can benefit from the new docs sooner.
This commit is contained in:
Henrik Lissner
commit
1f8bf7accb
179 changed files with 13125 additions and 8630 deletions
|
|
@ -1,83 +1,97 @@
|
|||
#+TITLE: editor/file-templates
|
||||
#+DATE: February 11, 2017
|
||||
#+SINCE: v2.0
|
||||
#+STARTUP: inlineimages
|
||||
# -*- mode: doom-docs-org -*-
|
||||
#+title: :editor file-templates
|
||||
#+subtitle: Fill the void in your empty files
|
||||
#+created: February 11, 2017
|
||||
#+since: 2.0.0
|
||||
|
||||
* Table of Contents :TOC_2:noexport:
|
||||
- [[#description][Description]]
|
||||
- [[#module-flags][Module Flags]]
|
||||
- [[#plugins][Plugins]]
|
||||
- [[#prerequisites][Prerequisites]]
|
||||
- [[#usage][Usage]]
|
||||
- [[#inserting-oss-licenses][Inserting OSS licenses]]
|
||||
- [[#configuration][Configuration]]
|
||||
- [[#registering-a-new-file-template][Registering a new file template]]
|
||||
- [[#changing-existing-file-templates][Changing existing file templates]]
|
||||
- [[#adding-new-oss-licenses][Adding new OSS licenses]]
|
||||
- [[#troubleshooting][Troubleshooting]]
|
||||
- [[#appendix][Appendix]]
|
||||
- [[#api][API]]
|
||||
- [[#commands][Commands]]
|
||||
- [[#variables][Variables]]
|
||||
* Description :unfold:
|
||||
This module adds file templates for blank files, powered by [[doom-package:][yasnippet]].
|
||||
|
||||
* Description
|
||||
This module adds file templates for blank files, powered by yasnippet.
|
||||
** Maintainers
|
||||
- [[doom-user:][@hlissner]]
|
||||
|
||||
** Module Flags
|
||||
This module provides no flags.
|
||||
[[doom-contrib-maintainer:][Become a maintainer?]]
|
||||
|
||||
** Plugins
|
||||
This module installs no plugins.
|
||||
** Module flags
|
||||
/This module has no flags./
|
||||
|
||||
* Prerequisites
|
||||
This module has no prerequisites.
|
||||
** Packages
|
||||
/This module doesn't install any packages./
|
||||
|
||||
* Usage
|
||||
File templates are automatically expanded when opening empty files.
|
||||
** Hacks
|
||||
- [[doom-package:][yasnippet]]
|
||||
|
||||
They are also regular yasnippet snippets, which can be expanded by typing their
|
||||
trigger and pressing =TAB=. By convention, the triggers for file templates are
|
||||
prefixed with two underscores ~__~.
|
||||
** TODO Changelog
|
||||
# This section will be machine generated. Don't edit it by hand.
|
||||
/This module does not have a changelog yet./
|
||||
|
||||
* Installation
|
||||
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
||||
|
||||
/This module has no external requirements./
|
||||
|
||||
* TODO Usage
|
||||
#+begin_quote
|
||||
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
File templates are automatically expanded when opening empty files who match one
|
||||
of the rules in the ~+file-templates-alist~ variable.
|
||||
|
||||
These templates are simply yasnippet snippets, which can also be expanded by
|
||||
typing their trigger and pressing [[kbd:][TAB]]. By convention, the triggers for file
|
||||
templates are prefixed with two underscores ~__~ (the trigger for the default
|
||||
file template of a major mode is almost always ~__~).
|
||||
|
||||
** Inserting OSS licenses
|
||||
A special command is available for inserting software licenses: ~M-x
|
||||
+file-templates/insert-license~.
|
||||
|
||||
#+begin_quote
|
||||
Licenses with a ~-bp~ suffix are boilerplate templates; shorter versions meant
|
||||
for comment headers in code.
|
||||
📌 Licenses with a ~-bp~ suffix are boilerplate templates; i.e. shorter
|
||||
versions intended for comment headers in code files.
|
||||
#+end_quote
|
||||
|
||||
* Configuration
|
||||
** Registering a new file template
|
||||
Look into the documentation of ~set-file-template!~ and ~set-file-templates!~.
|
||||
** Changing existing file templates
|
||||
Simply register a new template (using ~set-file-template!~) that matches the same
|
||||
file. The new template would be pushed to the top of ~+file-template-alist~ and
|
||||
thus would take priority while searching for a template to insert.
|
||||
** Adding new OSS licenses
|
||||
The ~+file-templates/insert-license~ command searches for snippets under
|
||||
~text-mode~ that are named ~__license-ABC~, where ABC is the short name of the
|
||||
license. e.g. ~__license-mit~.
|
||||
* TODO Configuration
|
||||
#+begin_quote
|
||||
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
So long as these files exist, ~+file-templates/insert-license~ will recognize
|
||||
them.
|
||||
** Adding new or changing existing file templates
|
||||
New file templates can be added to
|
||||
=$DOOMDIR/snippets/{major-mode}/{snippet-name}=. The yasnippet documentation
|
||||
covers [[https://joaotavora.github.io/yasnippet/snippet-development.html][how to write a snippet]]. You can map a snippet to a file path, major mode,
|
||||
or another arbitrary predicate using [[fn:][set-file-template!]].
|
||||
|
||||
Look into its documentation with [[kbd:][<help> f set-file-template\!]].
|
||||
|
||||
** Adding new OSS licenses
|
||||
Add snippet files to =$DOOMDIR/snippets/text-mode/= with the =__licenses-=
|
||||
prefix and [[fn:][+file-templates/insert-license]] will recognize them. E.g.
|
||||
=$DOOMDIR/snippets/text-mode/__license-mit=.
|
||||
|
||||
* Troubleshooting
|
||||
If a file template isn't expanding where you expect it to, run ~M-x
|
||||
+file-templates/debug~. This will report to you what file template rule would
|
||||
apply for the correct file.
|
||||
- If a file template isn't expanding where you expect it to, run ~M-x
|
||||
+file-templates/debug~. This will report to you what file template rule would
|
||||
apply for the correct file.
|
||||
|
||||
* Frequently asked questions
|
||||
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
|
||||
|
||||
* TODO Appendix
|
||||
#+begin_quote
|
||||
🔨 /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]]
|
||||
#+end_quote
|
||||
|
||||
* Appendix
|
||||
** API
|
||||
+ ~set-file-template! PRED &rest PLIST~
|
||||
+ ~set-file-templates! &rest TEMPLATES~
|
||||
- ~set-file-template! PRED &rest PLIST~
|
||||
- ~set-file-templates! &rest TEMPLATES~
|
||||
|
||||
** Commands
|
||||
+ ~+file-templates/insert-license~
|
||||
+ ~+file-templates/debug~
|
||||
- ~+file-templates/insert-license~
|
||||
- ~+file-templates/debug~
|
||||
|
||||
** Variables
|
||||
+ ~+file-templates-dir~
|
||||
+ ~+file-templates-default-trigger~
|
||||
+ ~+file-templates-alist~
|
||||
- ~+file-templates-dir~
|
||||
- ~+file-templates-default-trigger~
|
||||
- ~+file-templates-alist~
|
||||
|
|
|
|||
|
|
@ -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")
|
||||
("__")))))
|
||||
|
|
|
|||
|
|
@ -71,9 +71,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)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,10 @@
|
|||
# -*- mode: snippet -*-
|
||||
# name: Doom category readme
|
||||
# --
|
||||
#+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).
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
# -*- mode: snippet -*-
|
||||
# name: Doom documentation
|
||||
# --
|
||||
#+title: ${1:Title}
|
||||
#+subtitle: ${2:Subtitle}
|
||||
|
||||
$0
|
||||
|
|
@ -1,70 +1,194 @@
|
|||
# -*- 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
|
||||
#+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-tag:][v21.12.0]] [2021-12-30]
|
||||
*** [[doom-ref:a1b2c3d4][commit SUBJECT linked to github commit]]
|
||||
commit BODY
|
||||
*** [[doom-ref:a1b2c3d4][commit SUBJECT linked to github commit]]
|
||||
commit BODY
|
||||
*** [[doom-ref: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
|
||||
Loading…
Add table
Add a link
Reference in a new issue