diff --git a/nixos/doc/manual/development/building-parts.chapter.md b/nixos/doc/manual/development/building-parts.chapter.md new file mode 100644 index 000000000000..79ddaa37140b --- /dev/null +++ b/nixos/doc/manual/development/building-parts.chapter.md @@ -0,0 +1,74 @@ +# Building Specific Parts of NixOS {#sec-building-parts} + +With the command `nix-build`, you can build specific parts of your NixOS +configuration. This is done as follows: + +```ShellSession +$ cd /path/to/nixpkgs/nixos +$ nix-build -A config.option +``` + +where `option` is a NixOS option with type "derivation" (i.e. something +that can be built). Attributes of interest include: + +`system.build.toplevel` + +: The top-level option that builds the entire NixOS system. Everything + else in your configuration is indirectly pulled in by this option. + This is what `nixos-rebuild` builds and what `/run/current-system` + points to afterwards. + + A shortcut to build this is: + + ```ShellSession + $ nix-build -A system + ``` + +`system.build.manual.manualHTML` + +: The NixOS manual. + +`system.build.etc` + +: A tree of symlinks that form the static parts of `/etc`. + +`system.build.initialRamdisk` , `system.build.kernel` + +: The initial ramdisk and kernel of the system. This allows a quick + way to test whether the kernel and the initial ramdisk boot + correctly, by using QEMU's `-kernel` and `-initrd` options: + + ```ShellSession + $ nix-build -A config.system.build.initialRamdisk -o initrd + $ nix-build -A config.system.build.kernel -o kernel + $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null + ``` + +`system.build.nixos-rebuild` , `system.build.nixos-install` , `system.build.nixos-generate-config` + +: These build the corresponding NixOS commands. + +`systemd.units.unit-name.unit` + +: This builds the unit with the specified name. Note that since unit + names contain dots (e.g. `httpd.service`), you need to put them + between quotes, like this: + + ```ShellSession + $ nix-build -A 'config.systemd.units."httpd.service".unit' + ``` + + You can also test individual units, without rebuilding the whole + system, by putting them in `/run/systemd/system`: + + ```ShellSession + $ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \ + /run/systemd/system/tmp-httpd.service + # systemctl daemon-reload + # systemctl start tmp-httpd.service + ``` + + Note that the unit must not have the same name as any unit in + `/etc/systemd/system` since those take precedence over + `/run/systemd/system`. That's why the unit is installed as + `tmp-httpd.service` here. diff --git a/nixos/doc/manual/development/building-parts.xml b/nixos/doc/manual/development/building-parts.xml deleted file mode 100644 index 88369fb891b3..000000000000 --- a/nixos/doc/manual/development/building-parts.xml +++ /dev/null @@ -1,121 +0,0 @@ - - Building Specific Parts of NixOS - - With the command nix-build, you can build specific parts - of your NixOS configuration. This is done as follows: - -$ cd /path/to/nixpkgs/nixos -$ nix-build -A config.option - where option is a NixOS option with type - “derivation” (i.e. something that can be built). Attributes of interest - include: - - - - system.build.toplevel - - - - The top-level option that builds the entire NixOS system. Everything else - in your configuration is indirectly pulled in by this option. This is - what nixos-rebuild builds and what - /run/current-system points to afterwards. - - - A shortcut to build this is: - -$ nix-build -A system - - - - - - system.build.manual.manualHTML - - - - The NixOS manual. - - - - - - system.build.etc - - - - A tree of symlinks that form the static parts of - /etc. - - - - - - system.build.initialRamdisk - - - system.build.kernel - - - - The initial ramdisk and kernel of the system. This allows a quick way to - test whether the kernel and the initial ramdisk boot correctly, by using - QEMU’s and options: - -$ nix-build -A config.system.build.initialRamdisk -o initrd -$ nix-build -A config.system.build.kernel -o kernel -$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null - - - - - - - system.build.nixos-rebuild - - - system.build.nixos-install - - - system.build.nixos-generate-config - - - - These build the corresponding NixOS commands. - - - - - - systemd.units.unit-name.unit - - - - This builds the unit with the specified name. Note that since unit names - contain dots (e.g. httpd.service), you need to put - them between quotes, like this: - -$ nix-build -A 'config.systemd.units."httpd.service".unit' - - You can also test individual units, without rebuilding the whole system, - by putting them in /run/systemd/system: - -$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \ - /run/systemd/system/tmp-httpd.service -# systemctl daemon-reload -# systemctl start tmp-httpd.service - - Note that the unit must not have the same name as any unit in - /etc/systemd/system since those take precedence over - /run/systemd/system. That’s why the unit is - installed as tmp-httpd.service here. - - - - - - diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml index eb505567962c..670a391e3801 100644 --- a/nixos/doc/manual/development/development.xml +++ b/nixos/doc/manual/development/development.xml @@ -9,11 +9,11 @@ This chapter describes how you can modify and extend NixOS. - + - - + + - + diff --git a/nixos/doc/manual/development/sources.chapter.md b/nixos/doc/manual/development/sources.chapter.md new file mode 100644 index 000000000000..88173f7135bd --- /dev/null +++ b/nixos/doc/manual/development/sources.chapter.md @@ -0,0 +1,77 @@ +# Getting the Sources {#sec-getting-sources} + +By default, NixOS's `nixos-rebuild` command uses the NixOS and Nixpkgs +sources provided by the `nixos` channel (kept in +`/nix/var/nix/profiles/per-user/root/channels/nixos`). To modify NixOS, +however, you should check out the latest sources from Git. This is as +follows: + +```ShellSession +$ git clone https://github.com/NixOS/nixpkgs +$ cd nixpkgs +$ git remote update origin +``` + +This will check out the latest Nixpkgs sources to `./nixpkgs` the NixOS +sources to `./nixpkgs/nixos`. (The NixOS source tree lives in a +subdirectory of the Nixpkgs repository.) The `nixpkgs` repository has +branches that correspond to each Nixpkgs/NixOS channel (see +[](#sec-upgrading) for more information about channels). Thus, the +Git branch `origin/nixos-17.03` will contain the latest built and tested +version available in the `nixos-17.03` channel. + +It's often inconvenient to develop directly on the master branch, since +if somebody has just committed (say) a change to GCC, then the binary +cache may not have caught up yet and you'll have to rebuild everything +from source. So you may want to create a local branch based on your +current NixOS version: + +```ShellSession +$ nixos-version +17.09pre104379.6e0b727 (Hummingbird) + +$ git checkout -b local 6e0b727 +``` + +Or, to base your local branch on the latest version available in a NixOS +channel: + +```ShellSession +$ git remote update origin +$ git checkout -b local origin/nixos-17.03 +``` + +(Replace `nixos-17.03` with the name of the channel you want to use.) +You can use `git merge` or `git + rebase` to keep your local branch in sync with the channel, e.g. + +```ShellSession +$ git remote update origin +$ git merge origin/nixos-17.03 +``` + +You can use `git cherry-pick` to copy commits from your local branch to +the upstream branch. + +If you want to rebuild your system using your (modified) sources, you +need to tell `nixos-rebuild` about them using the `-I` flag: + +```ShellSession +# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs +``` + +If you want `nix-env` to use the expressions in `/my/sources`, use +`nix-env -f + /my/sources/nixpkgs`, or change the default by adding a symlink in +`~/.nix-defexpr`: + +```ShellSession +$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs +``` + +You may want to delete the symlink `~/.nix-defexpr/channels_root` to +prevent root's NixOS channel from clashing with your own tree (this may +break the command-not-found utility though). If you want to go back to +the default state, you may just remove the `~/.nix-defexpr` directory +completely, log out and log in again and it should have been recreated +with a link to the root channels. diff --git a/nixos/doc/manual/development/sources.xml b/nixos/doc/manual/development/sources.xml deleted file mode 100644 index b333ccabb420..000000000000 --- a/nixos/doc/manual/development/sources.xml +++ /dev/null @@ -1,85 +0,0 @@ - - Getting the Sources - - By default, NixOS’s nixos-rebuild command uses the NixOS - and Nixpkgs sources provided by the nixos channel (kept in - /nix/var/nix/profiles/per-user/root/channels/nixos). To - modify NixOS, however, you should check out the latest sources from Git. This - is as follows: - -$ git clone https://github.com/NixOS/nixpkgs -$ cd nixpkgs -$ git remote update origin - - This will check out the latest Nixpkgs sources to - ./nixpkgs the NixOS sources to - ./nixpkgs/nixos. (The NixOS source tree lives in a - subdirectory of the Nixpkgs repository.) The - nixpkgs repository has branches that correspond - to each Nixpkgs/NixOS channel (see for more - information about channels). Thus, the Git branch - origin/nixos-17.03 will contain the latest built and - tested version available in the nixos-17.03 channel. - - - It’s often inconvenient to develop directly on the master branch, since if - somebody has just committed (say) a change to GCC, then the binary cache may - not have caught up yet and you’ll have to rebuild everything from source. - So you may want to create a local branch based on your current NixOS version: - -$ nixos-version -17.09pre104379.6e0b727 (Hummingbird) - -$ git checkout -b local 6e0b727 - - Or, to base your local branch on the latest version available in a NixOS - channel: - -$ git remote update origin -$ git checkout -b local origin/nixos-17.03 - - (Replace nixos-17.03 with the name of the channel you want - to use.) You can use git merge or git - rebase to keep your local branch in sync with the channel, e.g. - -$ git remote update origin -$ git merge origin/nixos-17.03 - - You can use git cherry-pick to copy commits from your - local branch to the upstream branch. - - - If you want to rebuild your system using your (modified) sources, you need to - tell nixos-rebuild about them using the - flag: - -# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs - - - - If you want nix-env to use the expressions in - /my/sources, use nix-env -f - /my/sources/nixpkgs, or change the - default by adding a symlink in ~/.nix-defexpr: - -$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs - - You may want to delete the symlink - ~/.nix-defexpr/channels_root to prevent root’s NixOS - channel from clashing with your own tree (this may break the - command-not-found utility though). If you want to go back to the default - state, you may just remove the ~/.nix-defexpr directory - completely, log out and log in again and it should have been recreated with a - link to the root channels. - - - diff --git a/nixos/doc/manual/development/testing-installer.chapter.md b/nixos/doc/manual/development/testing-installer.chapter.md new file mode 100644 index 000000000000..2eaa01614920 --- /dev/null +++ b/nixos/doc/manual/development/testing-installer.chapter.md @@ -0,0 +1,18 @@ +# Testing the Installer {#ch-testing-installer} + +Building, burning, and booting from an installation CD is rather +tedious, so here is a quick way to see if the installer works properly: + +```ShellSession +# mount -t tmpfs none /mnt +# nixos-generate-config --root /mnt +$ nix-build '' -A config.system.build.nixos-install +# ./result/bin/nixos-install +``` + +To start a login shell in the new NixOS installation in `/mnt`: + +```ShellSession +$ nix-build '' -A config.system.build.nixos-enter +# ./result/bin/nixos-enter +``` diff --git a/nixos/doc/manual/development/testing-installer.xml b/nixos/doc/manual/development/testing-installer.xml deleted file mode 100644 index 902f995fbc1b..000000000000 --- a/nixos/doc/manual/development/testing-installer.xml +++ /dev/null @@ -1,22 +0,0 @@ - - Testing the Installer - - Building, burning, and booting from an installation CD is rather tedious, so - here is a quick way to see if the installer works properly: - -# mount -t tmpfs none /mnt -# nixos-generate-config --root /mnt -$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install -# ./result/bin/nixos-install - To start a login shell in the new NixOS installation in - /mnt: - -$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter -# ./result/bin/nixos-enter - - - diff --git a/nixos/doc/manual/development/writing-documentation.chapter.md b/nixos/doc/manual/development/writing-documentation.chapter.md new file mode 100644 index 000000000000..7c29f600d701 --- /dev/null +++ b/nixos/doc/manual/development/writing-documentation.chapter.md @@ -0,0 +1,93 @@ +# Writing NixOS Documentation {#sec-writing-documentation} + +As NixOS grows, so too does the need for a catalogue and explanation of +its extensive functionality. Collecting pertinent information from +disparate sources and presenting it in an accessible style would be a +worthy contribution to the project. + +## Building the Manual {#sec-writing-docs-building-the-manual} + +The DocBook sources of the [](#book-nixos-manual) are in the +[`nixos/doc/manual`](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) +subdirectory of the Nixpkgs repository. + +You can quickly validate your edits with `make`: + +```ShellSession +$ cd /path/to/nixpkgs/nixos/doc/manual +$ nix-shell +nix-shell$ make +``` + +Once you are done making modifications to the manual, it\'s important to +build it before committing. You can do that as follows: + +```ShellSession +nix-build nixos/release.nix -A manual.x86_64-linux +``` + +When this command successfully finishes, it will tell you where the +manual got generated. The HTML will be accessible through the `result` +symlink at `./result/share/doc/nixos/index.html`. + +## Editing DocBook XML {#sec-writing-docs-editing-docbook-xml} + +For general information on how to write in DocBook, see [DocBook 5: The +Definitive Guide](http://www.docbook.org/tdg5/en/html/docbook.html). + +Emacs nXML Mode is very helpful for editing DocBook XML because it +validates the document as you write, and precisely locates errors. To +use it, see [](#sec-emacs-docbook-xml). + +[Pandoc](http://pandoc.org) can generate DocBook XML from a multitude of +formats, which makes a good starting point. Here is an example of Pandoc +invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML: + +```ShellSession +pandoc -f markdown_github -t docbook5 docs.md -o my-section.md +``` + +Pandoc can also quickly convert a single `section.xml` to HTML, which is +helpful when drafting. + +Sometimes writing valid DocBook is simply too difficult. In this case, +submit your documentation updates in a [GitHub +Issue](https://github.com/NixOS/nixpkgs/issues/new) and someone will +handle the conversion to XML for you. + +## Creating a Topic {#sec-writing-docs-creating-a-topic} + +You can use an existing topic as a basis for the new topic or create a +topic from scratch. + +Keep the following guidelines in mind when you create and add a topic: + +- The NixOS [`book`](http://www.docbook.org/tdg5/en/html/book.html) + element is in `nixos/doc/manual/manual.xml`. It includes several + [`parts`](http://www.docbook.org/tdg5/en/html/book.html) which are in + subdirectories. + +- Store the topic file in the same directory as the `part` to which it + belongs. If your topic is about configuring a NixOS module, then the + XML file can be stored alongside the module definition `nix` file. + +- If you include multiple words in the file name, separate the words + with a dash. For example: `ipv6-config.xml`. + +- Make sure that the `xml:id` value is unique. You can use abbreviations + if the ID is too long. For example: `nixos-config`. + +- Determine whether your topic is a chapter or a section. If you are + unsure, open an existing topic file and check whether the main + element is chapter or section. + +## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic} + +Open the parent XML file and add an `xi:include` element to the list of +chapters with the file name of the topic that you created. If you +created a `section`, you add the file to the `chapter` file. If you created +a `chapter`, you add the file to the `part` file. + +If the topic is about configuring a NixOS module, it can be +automatically included in the manual by using the `meta.doc` attribute. +See [](#sec-meta-attributes) for an explanation. diff --git a/nixos/doc/manual/development/writing-documentation.xml b/nixos/doc/manual/development/writing-documentation.xml deleted file mode 100644 index 89fab6665616..000000000000 --- a/nixos/doc/manual/development/writing-documentation.xml +++ /dev/null @@ -1,150 +0,0 @@ - - Writing NixOS Documentation - - As NixOS grows, so too does the need for a catalogue and explanation of its - extensive functionality. Collecting pertinent information from disparate - sources and presenting it in an accessible style would be a worthy - contribution to the project. - -
- Building the Manual - - - The DocBook sources of the are in the - nixos/doc/manual - subdirectory of the Nixpkgs repository. - - - - You can quickly validate your edits with make: - - - -$ cd /path/to/nixpkgs/nixos/doc/manual -$ nix-shell -nix-shell$ make - - - - Once you are done making modifications to the manual, it's important to - build it before committing. You can do that as follows: - - -nix-build nixos/release.nix -A manual.x86_64-linux - - - When this command successfully finishes, it will tell you where the manual - got generated. The HTML will be accessible through the - result symlink at - ./result/share/doc/nixos/index.html. - -
-
- Editing DocBook XML - - - For general information on how to write in DocBook, see - DocBook - 5: The Definitive Guide. - - - - Emacs nXML Mode is very helpful for editing DocBook XML because it validates - the document as you write, and precisely locates errors. To use it, see - . - - - - Pandoc can generate DocBook XML - from a multitude of formats, which makes a good starting point. - - Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML -pandoc -f markdown_github -t docbook5 docs.md -o my-section.md - - Pandoc can also quickly convert a single section.xml to - HTML, which is helpful when drafting. - - - - Sometimes writing valid DocBook is simply too difficult. In this case, - submit your documentation updates in a - GitHub - Issue and someone will handle the conversion to XML for you. - -
-
- Creating a Topic - - - You can use an existing topic as a basis for the new topic or create a topic - from scratch. - - - - Keep the following guidelines in mind when you create and add a topic: - - - - The NixOS - book - element is in nixos/doc/manual/manual.xml. It - includes several - parts - which are in subdirectories. - - - - - Store the topic file in the same directory as the part to - which it belongs. If your topic is about configuring a NixOS module, then - the XML file can be stored alongside the module definition - nix file. - - - - - If you include multiple words in the file name, separate the words with a - dash. For example: ipv6-config.xml. - - - - - Make sure that the xml:id value is unique. You can use - abbreviations if the ID is too long. For example: - nixos-config. - - - - - Determine whether your topic is a chapter or a section. If you are - unsure, open an existing topic file and check whether the main element is - chapter or section. - - - - -
-
- Adding a Topic to the Book - - - Open the parent XML file and add an xi:include element to - the list of chapters with the file name of the topic that you created. If - you created a section, you add the file to the chapter - file. If you created a chapter, you add the file to the - part file. - - - - If the topic is about configuring a NixOS module, it can be automatically - included in the manual by using the meta.doc attribute. - See for an explanation. - -
- diff --git a/nixos/doc/manual/from_md/development/building-parts.chapter.xml b/nixos/doc/manual/from_md/development/building-parts.chapter.xml new file mode 100644 index 000000000000..4df24cc95652 --- /dev/null +++ b/nixos/doc/manual/from_md/development/building-parts.chapter.xml @@ -0,0 +1,124 @@ + + Building Specific Parts of NixOS + + With the command nix-build, you can build + specific parts of your NixOS configuration. This is done as follows: + + +$ cd /path/to/nixpkgs/nixos +$ nix-build -A config.option + + + where option is a NixOS option with type + derivation (i.e. something that can be built). + Attributes of interest include: + + + + + system.build.toplevel + + + + The top-level option that builds the entire NixOS system. + Everything else in your configuration is indirectly pulled in + by this option. This is what nixos-rebuild + builds and what /run/current-system points + to afterwards. + + + A shortcut to build this is: + + +$ nix-build -A system + + + + + + system.build.manual.manualHTML + + + + The NixOS manual. + + + + + + system.build.etc + + + + A tree of symlinks that form the static parts of + /etc. + + + + + + system.build.initialRamdisk , + system.build.kernel + + + + The initial ramdisk and kernel of the system. This allows a + quick way to test whether the kernel and the initial ramdisk + boot correctly, by using QEMU’s -kernel and + -initrd options: + + +$ nix-build -A config.system.build.initialRamdisk -o initrd +$ nix-build -A config.system.build.kernel -o kernel +$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null + + + + + + system.build.nixos-rebuild , + system.build.nixos-install , + system.build.nixos-generate-config + + + + These build the corresponding NixOS commands. + + + + + + systemd.units.unit-name.unit + + + + This builds the unit with the specified name. Note that since + unit names contain dots (e.g. + httpd.service), you need to put them + between quotes, like this: + + +$ nix-build -A 'config.systemd.units."httpd.service".unit' + + + You can also test individual units, without rebuilding the + whole system, by putting them in + /run/systemd/system: + + +$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \ + /run/systemd/system/tmp-httpd.service +# systemctl daemon-reload +# systemctl start tmp-httpd.service + + + Note that the unit must not have the same name as any unit in + /etc/systemd/system since those take + precedence over /run/systemd/system. That’s + why the unit is installed as + tmp-httpd.service here. + + + + + diff --git a/nixos/doc/manual/from_md/development/sources.chapter.xml b/nixos/doc/manual/from_md/development/sources.chapter.xml new file mode 100644 index 000000000000..aac18c9d06c8 --- /dev/null +++ b/nixos/doc/manual/from_md/development/sources.chapter.xml @@ -0,0 +1,90 @@ + + Getting the Sources + + By default, NixOS’s nixos-rebuild command uses + the NixOS and Nixpkgs sources provided by the + nixos channel (kept in + /nix/var/nix/profiles/per-user/root/channels/nixos). + To modify NixOS, however, you should check out the latest sources + from Git. This is as follows: + + +$ git clone https://github.com/NixOS/nixpkgs +$ cd nixpkgs +$ git remote update origin + + + This will check out the latest Nixpkgs sources to + ./nixpkgs the NixOS sources to + ./nixpkgs/nixos. (The NixOS source tree lives in + a subdirectory of the Nixpkgs repository.) The + nixpkgs repository has branches that correspond + to each Nixpkgs/NixOS channel (see + for more information about channels). Thus, the Git branch + origin/nixos-17.03 will contain the latest built + and tested version available in the nixos-17.03 + channel. + + + It’s often inconvenient to develop directly on the master branch, + since if somebody has just committed (say) a change to GCC, then the + binary cache may not have caught up yet and you’ll have to rebuild + everything from source. So you may want to create a local branch + based on your current NixOS version: + + +$ nixos-version +17.09pre104379.6e0b727 (Hummingbird) + +$ git checkout -b local 6e0b727 + + + Or, to base your local branch on the latest version available in a + NixOS channel: + + +$ git remote update origin +$ git checkout -b local origin/nixos-17.03 + + + (Replace nixos-17.03 with the name of the channel + you want to use.) You can use git merge or + git rebase to keep your local branch in sync with + the channel, e.g. + + +$ git remote update origin +$ git merge origin/nixos-17.03 + + + You can use git cherry-pick to copy commits from + your local branch to the upstream branch. + + + If you want to rebuild your system using your (modified) sources, + you need to tell nixos-rebuild about them using + the -I flag: + + +# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs + + + If you want nix-env to use the expressions in + /my/sources, use + nix-env -f /my/sources/nixpkgs, or change the + default by adding a symlink in ~/.nix-defexpr: + + +$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs + + + You may want to delete the symlink + ~/.nix-defexpr/channels_root to prevent root’s + NixOS channel from clashing with your own tree (this may break the + command-not-found utility though). If you want to go back to the + default state, you may just remove the + ~/.nix-defexpr directory completely, log out and + log in again and it should have been recreated with a link to the + root channels. + + diff --git a/nixos/doc/manual/from_md/development/testing-installer.chapter.xml b/nixos/doc/manual/from_md/development/testing-installer.chapter.xml new file mode 100644 index 000000000000..286d49f3c291 --- /dev/null +++ b/nixos/doc/manual/from_md/development/testing-installer.chapter.xml @@ -0,0 +1,22 @@ + + Testing the Installer + + Building, burning, and booting from an installation CD is rather + tedious, so here is a quick way to see if the installer works + properly: + + +# mount -t tmpfs none /mnt +# nixos-generate-config --root /mnt +$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install +# ./result/bin/nixos-install + + + To start a login shell in the new NixOS installation in + /mnt: + + +$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter +# ./result/bin/nixos-enter + + diff --git a/nixos/doc/manual/from_md/development/writing-documentation.chapter.xml b/nixos/doc/manual/from_md/development/writing-documentation.chapter.xml new file mode 100644 index 000000000000..a42067f4e995 --- /dev/null +++ b/nixos/doc/manual/from_md/development/writing-documentation.chapter.xml @@ -0,0 +1,144 @@ + + Writing NixOS Documentation + + As NixOS grows, so too does the need for a catalogue and explanation + of its extensive functionality. Collecting pertinent information + from disparate sources and presenting it in an accessible style + would be a worthy contribution to the project. + +
+ Building the Manual + + The DocBook sources of the + are in the + nixos/doc/manual + subdirectory of the Nixpkgs repository. + + + You can quickly validate your edits with make: + + +$ cd /path/to/nixpkgs/nixos/doc/manual +$ nix-shell +nix-shell$ make + + + Once you are done making modifications to the manual, it's + important to build it before committing. You can do that as + follows: + + +nix-build nixos/release.nix -A manual.x86_64-linux + + + When this command successfully finishes, it will tell you where + the manual got generated. The HTML will be accessible through the + result symlink at + ./result/share/doc/nixos/index.html. + +
+
+ Editing DocBook XML + + For general information on how to write in DocBook, see + DocBook + 5: The Definitive Guide. + + + Emacs nXML Mode is very helpful for editing DocBook XML because it + validates the document as you write, and precisely locates errors. + To use it, see . + + + Pandoc can generate + DocBook XML from a multitude of formats, which makes a good + starting point. Here is an example of Pandoc invocation to convert + GitHub-Flavoured MarkDown to DocBook 5 XML: + + +pandoc -f markdown_github -t docbook5 docs.md -o my-section.md + + + Pandoc can also quickly convert a single + section.xml to HTML, which is helpful when + drafting. + + + Sometimes writing valid DocBook is simply too difficult. In this + case, submit your documentation updates in a + GitHub + Issue and someone will handle the conversion to XML for + you. + +
+
+ Creating a Topic + + You can use an existing topic as a basis for the new topic or + create a topic from scratch. + + + Keep the following guidelines in mind when you create and add a + topic: + + + + + The NixOS + book + element is in nixos/doc/manual/manual.xml. + It includes several + parts + which are in subdirectories. + + + + + Store the topic file in the same directory as the + part to which it belongs. If your topic is + about configuring a NixOS module, then the XML file can be + stored alongside the module definition nix + file. + + + + + If you include multiple words in the file name, separate the + words with a dash. For example: + ipv6-config.xml. + + + + + Make sure that the xml:id value is unique. + You can use abbreviations if the ID is too long. For example: + nixos-config. + + + + + Determine whether your topic is a chapter or a section. If you + are unsure, open an existing topic file and check whether the + main element is chapter or section. + + + +
+
+ Adding a Topic to the Book + + Open the parent XML file and add an xi:include + element to the list of chapters with the file name of the topic + that you created. If you created a section, you + add the file to the chapter file. If you + created a chapter, you add the file to the + part file. + + + If the topic is about configuring a NixOS module, it can be + automatically included in the manual by using the + meta.doc attribute. See + for an explanation. + +
+