aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorjgart <jgart@dismail.de>2022-01-15 14:45:22 -0500
committerMaxim Cournoyer <maxim.cournoyer@gmail.com>2022-07-07 14:40:50 -0400
commite103d6148567d2248cd951f2e2507bdaf4914c29 (patch)
tree1578f35cb5999c1f40975b541b81633bd5ecb2f0
parent3e8a1e8f25cea57ebaa6cd9ba41e4aa507148503 (diff)
downloadguix-e103d6148567d2248cd951f2e2507bdaf4914c29.tar
guix-e103d6148567d2248cd951f2e2507bdaf4914c29.tar.gz
doc: Document the documentation process.
* doc/contributing.texi (Contributing): Add Writing Documentation section. Co-authored-by: Julien Lepiller <julien@lepiller.eu> Co-authored-by: Matt Trzcinski <matt@excalamus.com> Co-authored-by: Fabio Natali <me@fabionatali.com> Co-authored-by: Gabor Boskovits <boskovits@gmail.com> Co-authored-by: Luis Felipe <luis.felipe.la@protonmail.com> Signed-off-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
-rw-r--r--doc/contributing.texi42
1 files changed, 42 insertions, 0 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi
index e1902f120f..dcb45ad34c 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -29,6 +29,7 @@ choice.
* Tracking Bugs and Patches:: Keeping it all organized.
* Commit Access:: Pushing to the official repository.
* Updating the Guix Package:: Updating the Guix package definition.
+* Writing Documentation:: Improving documentation in GNU Guix.
* Translating Guix:: Make Guix speak your native language.
@end menu
@@ -1779,6 +1780,47 @@ This check can be disabled, @emph{at your own peril}, by setting the
this variable is set, the updated package source is also added to the
store. This is used as part of the release process of Guix.
+@cindex documentation
+@node Writing Documentation
+@section Writing Documentation
+
+Guix is documented using the Texinfo system. If you are not yet
+familiar with it, we accept contributions for documentation in most
+formats. That includes plain text, Markdown, Org, etc.
+
+Documentation contributions can be sent to
+@email{guix-patches@@gnu.org}. Prepend @samp{[DOCUMENTATION]} to the
+subject.
+
+When you need to make more than a simple addition to the documentation,
+we prefer that you send a proper patch as opposed to sending an email
+as described above. @xref{Submitting Patches} for more information on
+how to send your patches.
+
+To modify the documentation, you need to edit @file{doc/guix.texi} and
+@file{doc/contributing.texi} (which contains this documentation
+section), or @file{doc/guix-cookbook.texi} for the cookbook. If
+you compiled the Guix repository before, you will have
+many more @file{.texi} files that are translations of these
+documents. Do not modify them, the translation is managed through
+@uref{https://translate.fedoraproject.org/projects/guix, Weblate}.
+@xref{Translating Guix} for more information.
+
+To render documentation, you must first make sure that you ran
+@command{./configure} in your source tree (@pxref{Running Guix Before
+It Is Installed}). After that you can run one of the following
+commands:
+
+@itemize
+@item @samp{make doc/guix.info} to compile the Info manual.
+ You can check it with @command{info doc/guix.info}.
+@item @samp{make doc/guix.html} to compile the HTML version.
+ You can point your browser to the relevant file in the
+ @file{doc/guix.html} directory.
+@item @samp{make doc/guix-cookbook.info} for the cookbook Info manual.
+@item @samp{make doc/guix-cookbook.html} for the cookbook HTML version.
+@end itemize
+
@cindex translation
@cindex l10n
@cindex i18n