From 8db0e184380c8bde8a4ab65d913370761c20e5b4 Mon Sep 17 00:00:00 2001 From: Antoine Eiche Date: Mon, 6 Jul 2020 22:23:03 +0200 Subject: [PATCH] docs: how to contribute to documentation --- docs/howto-develop.rst | 37 ++++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/docs/howto-develop.rst b/docs/howto-develop.rst index 3a6361c..173c4f3 100644 --- a/docs/howto-develop.rst +++ b/docs/howto-develop.rst @@ -1,17 +1,36 @@ How to Develop SNM ================== -Run tests ---------- +Run NixOS tests +--------------- You can run the testsuite via :: - nix-build tests -A extern.nixpkgs_20_03 - nix-build tests -A intern.nixpkgs_unstable + $ nix-build tests -A extern.nixpkgs_20_03 + $ nix-build tests -A intern.nixpkgs_unstable ... +Contributing to the documentation +--------------------------------- + +The documentation is written in RST, build with Sphinx and published +by `Read the Docs `_. + +For the syntax, see `RST/Sphinx Cheatsheet +`_. + +The ``shell.nix`` provides all the tooling required to build the +documentation: + +:: + + $ nix-shell + $ cd docs + $ make html + $ firefox ./_build/html/index.html + Nixops ------ @@ -19,15 +38,15 @@ You can test the setup via ``nixops``. After installation, do :: - nixops create nixops/single-server.nix nixops/vbox.nix -d mail - nixops deploy -d mail - nixops info -d mail + $ nixops create nixops/single-server.nix nixops/vbox.nix -d mail + $ nixops deploy -d mail + $ nixops info -d mail You can then test the server via e.g. \ ``telnet``. To log into it, use :: - nixops ssh -d mail mailserver + $ nixops ssh -d mail mailserver Imap ---- @@ -36,4 +55,4 @@ To test imap manually use :: - openssl s_client -host mail.example.com -port 143 -starttls imap + $ openssl s_client -host mail.example.com -port 143 -starttls imap