Add spacing conventions for writing documentation.
These were briefly discussed in #2124.
This commit is contained in:
parent
2e48e5568a
commit
640366e9ae
|
@ -11,11 +11,10 @@
|
|||
- [[#key-bindings][Key bindings]]
|
||||
|
||||
** Description
|
||||
|
||||
This layer does wondeful things: - thing01
|
||||
This layer does wonderful things:
|
||||
- thing01
|
||||
|
||||
** Install
|
||||
|
||||
To use this contribution add it to your =~/.spacemacs=
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
|
|
|
@ -52,14 +52,14 @@ Contributed configuration layers are stored in the =contrib= folder. The
|
|||
layers in. For example a layer for a language would go in the
|
||||
=contrib/!lang= folder.
|
||||
|
||||
It is recommended to join a =README.md= file with your layer: - ideally
|
||||
this file should document the packages of your layer as well as the key
|
||||
bindings associated with them, - a template is provided in
|
||||
=~/.emacs.d/core/templates/layer-README.template=, use it as much as
|
||||
possible, - another good practice is to start from the =README.md= of an
|
||||
existing layer, - if a logo exists for the layer you can
|
||||
add it at the top of the =README.md= before the TOC. The maximum
|
||||
recommended height is 200 pixels.
|
||||
It is recommended to join a =README.org= file with your layer:
|
||||
- ideally this file should document the packages of your layer as well as the
|
||||
key bindings associated with them
|
||||
- a template is provided in =~/.emacs.d/core/templates/layer-README.template=,
|
||||
use it as much as possible
|
||||
- another good practice is to start from the =README.org= of an existing layer
|
||||
- if a logo exists for the layer you can add it at the top of the =README.org=
|
||||
before the TOC. The maximum recommended height is 200 pixels.
|
||||
|
||||
** Submitting a banner
|
||||
The startup banner is by default randomly chosen among a pool of banners
|
||||
|
|
|
@ -33,6 +33,8 @@
|
|||
- [[#language-specific][Language specific]]
|
||||
- [[#refactoring][Refactoring]]
|
||||
- [[#help-or-documentation][Help or Documentation]]
|
||||
- [[#writing-documentation][Writing documentation]]
|
||||
- [[#spacing-in-documentation][Spacing in documentation]]
|
||||
|
||||
** Code guidelines
|
||||
*** Spacemacs core and layer
|
||||
|
@ -302,3 +304,17 @@ as an help command.
|
|||
|---------+------------------------------------|
|
||||
| ~m h h~ | documentation of thing under point |
|
||||
| ~m h r~ | documentation of selected region |
|
||||
|
||||
** Writing documentation
|
||||
Spacemacs provides an example layer =README.org= file in
|
||||
=~/.emacs.d/core/templates/layer-README.template=.
|
||||
|
||||
*** Spacing in documentation
|
||||
Spacemacs tries to keep the documentation consistent between all layers by
|
||||
providing some rules for spacing:
|
||||
- After each header, you should not add an empty line
|
||||
- *Exception*: If the first item under the header is a table, add an empty
|
||||
line after it
|
||||
- At the end of each header node, there should be an empty line
|
||||
- Note: Many layer =READMEs= do not follow this convention yet. Please fix
|
||||
them if you can.
|
||||
|
|
Loading…
Reference in New Issue