nixos/doc: add md-to-db.sh, convert "Building Your Own NixOS CD" to CommonMark

This commit is contained in:
Ryan Mulligan 2020-12-22 21:56:46 -08:00 committed by Jonathan Ringer
parent ff1ded3e20
commit 6c14851943
7 changed files with 109 additions and 34 deletions

20
.github/workflows/nixos-manual.yml vendored Normal file
View File

@ -0,0 +1,20 @@
name: NixOS manual checks
on:
pull_request:
branches-ignore:
- 'release-**'
paths:
- 'nixos/**/*.xml'
- 'nixos/**/*.md'
jobs:
tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: cachix/install-nix-action@v12
- name: Check DocBook files generated from Markdown are consistent
run: |
nixos/doc/manual/md-to-db.sh
git diff --exit-code

View File

@ -0,0 +1,18 @@
# Building Your Own NixOS CD {#sec-building-cd}
Building a NixOS CD is as easy as configuring your own computer. The idea is to use another module which will replace your `configuration.nix` to configure the system that would be installed on the CD.
Default CD/DVD configurations are available inside `nixos/modules/installer/cd-dvd`
```ShellSession
$ git clone https://github.com/NixOS/nixpkgs.git
$ cd nixpkgs/nixos
$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix
```
Before burning your CD/DVD, you can check the content of the image by mounting anywhere like suggested by the following command:
```ShellSession
# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>
```
If you want to customize your NixOS CD in more detail, or generate other kinds of images, you might want to check out [nixos-generators](https://github.com/nix-community/nixos-generators). This can also be a good starting point when you want to use Nix to build a 'minimal' image that doesn't include a NixOS installation.

View File

@ -1,33 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-building-cd">
<title>Building Your Own NixOS CD</title>
<para>
Building a NixOS CD is as easy as configuring your own computer. The idea is
to use another module which will replace your
<filename>configuration.nix</filename> to configure the system that would be
installed on the CD.
</para>
<para>
Default CD/DVD configurations are available inside
<filename>nixos/modules/installer/cd-dvd</filename>.
<screen>
<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs.git
<prompt>$ </prompt>cd nixpkgs/nixos
<prompt>$ </prompt>nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix</screen>
</para>
<para>
Before burning your CD/DVD, you can check the content of the image by
mounting anywhere like suggested by the following command:
<screen>
<prompt># </prompt>mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>
</para>
<para>
If you want to customize your NixOS CD in more detail, or generate other kinds
of images, you might want to check out <link
xlink:href="https://github.com/nix-community/nixos-generators">nixos-generators</link>. This can also be a good starting point when you want to use Nix to build a
'minimal' image that doesn't include a NixOS installation.
</para>
</chapter>

View File

@ -13,7 +13,7 @@
<xi:include href="writing-modules.xml" />
<xi:include href="building-parts.xml" />
<xi:include href="writing-documentation.xml" />
<xi:include href="building-nixos.xml" />
<xi:include href="../from_md/development/building-nixos.chapter.xml" />
<xi:include href="nixos-tests.xml" />
<xi:include href="testing-installer.xml" />
<xi:include href="releases.xml" />

View File

@ -0,0 +1,5 @@
This directory is temporarily needed while we transition the manual to CommonMark. It stores the output of the ../md-to-db.sh script that converts CommonMark files back to DocBook.
We are choosing to convert the Markdown to DocBook at authoring time instead of manual building time, because we do not want the pandoc toolchain to become part of the NixOS closure.
Do not edit the DocBook files inside this directory or its subdirectories. Instead, edit the corresponding .md file in the normal manual directories, and run ../md-to-db.sh to update the file here.

View File

@ -0,0 +1,33 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-building-cd">
<title>Building Your Own NixOS CD</title>
<para>
Building a NixOS CD is as easy as configuring your own computer. The
idea is to use another module which will replace your
<literal>configuration.nix</literal> to configure the system that
would be installed on the CD.
</para>
<para>
Default CD/DVD configurations are available inside
<literal>nixos/modules/installer/cd-dvd</literal>
</para>
<programlisting>
$ git clone https://github.com/NixOS/nixpkgs.git
$ cd nixpkgs/nixos
$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix
</programlisting>
<para>
Before burning your CD/DVD, you can check the content of the image
by mounting anywhere like suggested by the following command:
</para>
<programlisting>
# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso&lt;/screen&gt;
</programlisting>
<para>
If you want to customize your NixOS CD in more detail, or generate
other kinds of images, you might want to check out
<link xlink:href="https://github.com/nix-community/nixos-generators">nixos-generators</link>.
This can also be a good starting point when you want to use Nix to
build a <quote>minimal</quote> image that doesnt include a NixOS
installation.
</para>
</chapter>

32
nixos/doc/manual/md-to-db.sh Executable file
View File

@ -0,0 +1,32 @@
#! /usr/bin/env nix-shell
#! nix-shell -I nixpkgs=channel:nixpkgs-unstable -i bash -p pandoc
# This script is temporarily needed while we transition the manual to
# CommonMark. It converts the .md files in the regular manual folder
# into DocBook files in the from_md folder.
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
pushd $DIR
OUT="$DIR/from_md"
mapfile -t MD_FILES < <(find . -type f -regex '.*\.md$')
for mf in ${MD_FILES[*]}; do
mkdir -p $(dirname "$OUT/$mf")
if [ "${mf: -11}" == ".section.md" ]; then
pandoc "$mf" -t docbook \
--extract-media=media \
-f markdown+smart \
| cat > "$OUT/${mf%".section.md"}.section.xml"
fi
if [ "${mf: -11}" == ".chapter.md" ]; then
pandoc "$mf" -t docbook \
--top-level-division=chapter \
--extract-media=media \
-f markdown+smart \
| cat > "$OUT/${mf%".chapter.md"}.chapter.xml"
fi
done
popd