Mirrors/home-manager
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

doc: add "Add relevant documentation" guideline

Browse source 
This adds a new section to the contributing guidelines that discusses
how contributions should be documented.

PR #1306
This commit is contained in:
Damien Cassou 2020-06-06 22:12:13 +02:00 committed by Robert Helgesson
parent 6f683d9726
commit 4ba9cedd68
No known key found for this signature in database
GPG key ID: 36BDAA14C2797E89
1 changed files with 20 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
doc/contributing.adoc
View file

@ -84,6 +84,26 @@ If at all possible, make sure to add new tests and expand existing tests so that
All contributed code _must_ pass the test suite.
[[sec-guidelines-module-maintainer]]
==== Add relevant documentation
:docbook: https://tdg.docbook.org/
:asciidoc: https://asciidoc.org/
:docbook-rocks: https://docbook.rocks/
Many code changes require changing the documentation as well. Module options should be documented with DocBook. See {docbook-rocks}[DocBook rocks!] for a quick introduction and {docbook}[DocBook 5: The Definitive Guide] for in-depth information of DocBook. Home Manager is itself documented using a combination of DocBook and {asciidoc}[AsciiDoc]. All text is hosted in Home Manager's Git repository.
The HTML version of the manual containing both the module option descriptions and the documentation of Home Manager can be generated and opened by typing the following in a shell within a clone of the Home Manager Git repository:
[source,console]
$ nix-build -A docs.html
$ xdg-open ./result/share/doc/home-manager/index.html
When you have made changes to a module, it is a good idea to check that the man page version of the module options looks good:
[source,console]
$ nix-build -A docs.manPages
$ man ./result/share/man/man5/home-configuration.nix.5
==== Add yourself as a module maintainer
Every new module _must_ include a named maintainer using the `meta.maintainers` attribute. If you are a user of a module that currently lacks a maintainer then please consider adopting it.