From 92d53362d4da7e19b6a7a6b1b936a0a34a17c0c9 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Sat, 24 Mar 2018 10:47:41 -0400 Subject: [PATCH 1/7] Move all nixpkgs doc files in to the doc directory This makes a makefile-driven developer workflow nicer. --- doc/default.nix | 40 +++--- ...ntroduction.md => introduction.chapter.md} | 0 .../{emscripten.md => emscripten.section.md} | 0 .../{haskell.md => haskell.section.md} | 0 doc/languages-frameworks/idris.section.md | 39 ++++++ doc/languages-frameworks/index.xml | 16 +-- doc/languages-frameworks/node.section.md | 51 ++++++++ .../{python.md => python.section.md} | 0 doc/languages-frameworks/r.section.md | 120 +++++++++++++++++ .../{rust.md => rust.section.md} | 0 .../{vim.md => vim.section.md} | 0 doc/manual.xml | 2 +- doc/{shell.md => shell.section.md} | 0 pkgs/development/idris-modules/README.md | 40 +----- pkgs/development/node-packages/README.md | 52 +------- pkgs/development/r-modules/README.md | 121 +----------------- 16 files changed, 242 insertions(+), 239 deletions(-) rename doc/{introduction.md => introduction.chapter.md} (100%) rename doc/languages-frameworks/{emscripten.md => emscripten.section.md} (100%) rename doc/languages-frameworks/{haskell.md => haskell.section.md} (100%) create mode 100644 doc/languages-frameworks/idris.section.md create mode 100644 doc/languages-frameworks/node.section.md rename doc/languages-frameworks/{python.md => python.section.md} (100%) create mode 100644 doc/languages-frameworks/r.section.md rename doc/languages-frameworks/{rust.md => rust.section.md} (100%) rename doc/languages-frameworks/{vim.md => vim.section.md} (100%) rename doc/{shell.md => shell.section.md} (100%) diff --git a/doc/default.nix b/doc/default.nix index ec458634a42..1adcd796820 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -45,45 +45,45 @@ pkgs.stdenv.mkDerivation { cp -s '${sources-langs}'/* ./languages-frameworks '' + toDocbook { - inputFile = ./introduction.md; - outputFile = "introduction.xml"; + inputFile = ./introduction.chapter.md; + outputFile = "introduction.chapter.xml"; useChapters = true; } + toDocbook { - inputFile = ./shell.md; - outputFile = "shell.xml"; + inputFile = ./shell.section.md; + outputFile = "shell.section.xml"; } + toDocbook { - inputFile = ./languages-frameworks/python.md; - outputFile = "./languages-frameworks/python.xml"; + inputFile = ./languages-frameworks/python.section.md; + outputFile = "./languages-frameworks/python.section.xml"; } + toDocbook { - inputFile = ./languages-frameworks/haskell.md; - outputFile = "./languages-frameworks/haskell.xml"; + inputFile = ./languages-frameworks/haskell.section.md; + outputFile = "./languages-frameworks/haskell.section.xml"; } + toDocbook { - inputFile = ../pkgs/development/idris-modules/README.md; - outputFile = "languages-frameworks/idris.xml"; + inputFile = ./languages-frameworks/idris.section.md; + outputFile = "languages-frameworks/idris.section.xml"; } + toDocbook { - inputFile = ../pkgs/development/node-packages/README.md; - outputFile = "languages-frameworks/node.xml"; + inputFile = ./languages-frameworks/node.section.md; + outputFile = "languages-frameworks/node.section.xml"; } + toDocbook { - inputFile = ../pkgs/development/r-modules/README.md; - outputFile = "languages-frameworks/r.xml"; + inputFile = ./languages-frameworks/r.section.md; + outputFile = "languages-frameworks/r.section.xml"; } + toDocbook { - inputFile = ./languages-frameworks/rust.md; - outputFile = "./languages-frameworks/rust.xml"; + inputFile = ./languages-frameworks/rust.section.md; + outputFile = "./languages-frameworks/rust.section.xml"; } + toDocbook { - inputFile = ./languages-frameworks/vim.md; - outputFile = "./languages-frameworks/vim.xml"; + inputFile = ./languages-frameworks/vim.section.md; + outputFile = "./languages-frameworks/vim.section.xml"; } + toDocbook { - inputFile = ./languages-frameworks/emscripten.md; - outputFile = "./languages-frameworks/emscripten.xml"; + inputFile = ./languages-frameworks/emscripten.section.md; + outputFile = "./languages-frameworks/emscripten.section.xml"; } + '' echo ${lib.nixpkgsVersion} > .version diff --git a/doc/introduction.md b/doc/introduction.chapter.md similarity index 100% rename from doc/introduction.md rename to doc/introduction.chapter.md diff --git a/doc/languages-frameworks/emscripten.md b/doc/languages-frameworks/emscripten.section.md similarity index 100% rename from doc/languages-frameworks/emscripten.md rename to doc/languages-frameworks/emscripten.section.md diff --git a/doc/languages-frameworks/haskell.md b/doc/languages-frameworks/haskell.section.md similarity index 100% rename from doc/languages-frameworks/haskell.md rename to doc/languages-frameworks/haskell.section.md diff --git a/doc/languages-frameworks/idris.section.md b/doc/languages-frameworks/idris.section.md new file mode 100644 index 00000000000..005ed360285 --- /dev/null +++ b/doc/languages-frameworks/idris.section.md @@ -0,0 +1,39 @@ +Idris packages +============== + +This directory contains build rules for idris packages. In addition, +it contains several functions to build and compose those packages. +Everything is exposed to the user via the `idrisPackages` attribute. + +callPackage +------------ + +This is like the normal nixpkgs callPackage function, specialized to +idris packages. + +builtins +--------- + +This is a list of all of the libraries that come packaged with Idris +itself. + +build-idris-package +-------------------- + +A function to build an idris package. Its sole argument is a set like +you might pass to `stdenv.mkDerivation`, except `build-idris-package` +sets several attributes for you. See `build-idris-package.nix` for +details. + +build-builtin-package +---------------------- + +A version of `build-idris-package` specialized to builtin libraries. +Mostly for internal use. + +with-packages +------------- + +Bundle idris together with a list of packages. Because idris currently +only supports a single directory in its library path, you must include +all desired libraries here, including `prelude` and `base`. \ No newline at end of file diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml index 6743c131201..a1c265f6748 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -17,20 +17,20 @@ such as Perl or Haskell. These are described in this chapter. - - + + - + - + - + - + - - + + diff --git a/doc/languages-frameworks/node.section.md b/doc/languages-frameworks/node.section.md new file mode 100644 index 00000000000..17a203ed12b --- /dev/null +++ b/doc/languages-frameworks/node.section.md @@ -0,0 +1,51 @@ +Node.js packages +================ +The `pkgs/development/node-packages` folder contains a generated collection of +[NPM packages](https://npmjs.com/) that can be installed with the Nix package +manager. + +As a rule of thumb, the package set should only provide *end user* software +packages, such as command-line utilities. Libraries should only be added to the +package set if there is a non-NPM package that requires it. + +When it is desired to use NPM libraries in a development project, use the +`node2nix` generator directly on the `package.json` configuration file of the +project. + +The package set also provides support for multiple Node.js versions. The policy +is that a new package should be added to the collection for the latest stable LTS +release (which is currently 6.x), unless there is an explicit reason to support +a different release. + +If your package uses native addons, you need to examine what kind of native +build system it uses. Here are some examples: + +* `node-gyp` +* `node-gyp-builder` +* `node-pre-gyp` + +After you have identified the correct system, you need to override your package +expression while adding in build system as a build input. For example, `dat` +requires `node-gyp-build`, so we override its expression in `default-v6.nix`: + +```nix +dat = nodePackages.dat.override (oldAttrs: { + buildInputs = oldAttrs.buildInputs ++ [ nodePackages.node-gyp-build ]; +}); +``` + +To add a package from NPM to nixpkgs: + + 1. Modify `pkgs/development/node-packages/node-packages-v6.json` to add, update + or remove package entries. (Or `pkgs/development/node-packages/node-packages-v4.json` + for packages depending on Node.js 4.x) + 2. Run the script: `(cd pkgs/development/node-packages && ./generate.sh)`. + 3. Build your new package to test your changes: + `cd /path/to/nixpkgs && nix-build -A nodePackages.`. + To build against a specific Node.js version (e.g. 4.x): + `nix-build -A nodePackages_4_x.` + 4. Add and commit all modified and generated files. + +For more information about the generation process, consult the +[README.md](https://github.com/svanderburg/node2nix) file of the `node2nix` +tool. diff --git a/doc/languages-frameworks/python.md b/doc/languages-frameworks/python.section.md similarity index 100% rename from doc/languages-frameworks/python.md rename to doc/languages-frameworks/python.section.md diff --git a/doc/languages-frameworks/r.section.md b/doc/languages-frameworks/r.section.md new file mode 100644 index 00000000000..c8f02bd1478 --- /dev/null +++ b/doc/languages-frameworks/r.section.md @@ -0,0 +1,120 @@ +R packages +========== + +## Installation + +Define an environment for R that contains all the libraries that you'd like to +use by adding the following snippet to your $HOME/.config/nixpkgs/config.nix file: + +```nix +{ + packageOverrides = super: let self = super.pkgs; in + { + + rEnv = super.rWrapper.override { + packages = with self.rPackages; [ + devtools + ggplot2 + reshape2 + yaml + optparse + ]; + }; + }; +} +``` + +Then you can use `nix-env -f "" -iA rEnv` to install it into your user +profile. The set of available libraries can be discovered by running the +command `nix-env -f "" -qaP -A rPackages`. The first column from that +output is the name that has to be passed to rWrapper in the code snipped above. + +However, if you'd like to add a file to your project source to make the +environment available for other contributors, you can create a `default.nix` +file like so: +```nix +let + pkgs = import {}; + stdenv = pkgs.stdenv; +in with pkgs; { + myProject = stdenv.mkDerivation { + name = "myProject"; + version = "1"; + src = if pkgs.lib.inNixShell then null else nix; + + buildInputs = with rPackages; [ + R + ggplot2 + knitr + ]; + }; +} +``` +and then run `nix-shell .` to be dropped into a shell with those packages +available. + +## RStudio + +RStudio uses a standard set of packages and ignores any custom R +environments or installed packages you may have. To create a custom +environment, see `rstudioWrapper`, which functions similarly to +`rWrapper`: + +```nix +{ + packageOverrides = super: let self = super.pkgs; in + { + + rstudioEnv = super.rstudioWrapper.override { + packages = with self.rPackages; [ + dplyr + ggplot2 + reshape2 + ]; + }; + }; +} +``` + +Then like above, `nix-env -f "" -iA rstudioEnv` will install +this into your user profile. + +Alternatively, you can create a self-contained `shell.nix` without the need to +modify any configuration files: + +```nix +{ pkgs ? import {} +}: + +pkgs.rstudioWrapper.override { + packages = with pkgs.rPackages; [ dplyr ggplot2 reshape2 ]; +} + +``` + +Executing `nix-shell` will then drop you into an environment equivalent to the +one above. If you need additional packages just add them to the list and +re-enter the shell. + +## Updating the package set + +```bash +nix-shell generate-shell.nix + +Rscript generate-r-packages.R cran > cran-packages.nix.new +mv cran-packages.nix.new cran-packages.nix + +Rscript generate-r-packages.R bioc > bioc-packages.nix.new +mv bioc-packages.nix.new bioc-packages.nix +``` + +`generate-r-packages.R ` reads `-packages.nix`, therefor the renaming. + + +## Testing if the Nix-expression could be evaluated + +```bash +nix-build test-evaluation.nix --dry-run +``` + +If this exits fine, the expression is ok. If not, you have to edit `default.nix` diff --git a/doc/languages-frameworks/rust.md b/doc/languages-frameworks/rust.section.md similarity index 100% rename from doc/languages-frameworks/rust.md rename to doc/languages-frameworks/rust.section.md diff --git a/doc/languages-frameworks/vim.md b/doc/languages-frameworks/vim.section.md similarity index 100% rename from doc/languages-frameworks/vim.md rename to doc/languages-frameworks/vim.section.md diff --git a/doc/manual.xml b/doc/manual.xml index eb0a24789d4..385079eb578 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -9,7 +9,7 @@ - + diff --git a/doc/shell.md b/doc/shell.section.md similarity index 100% rename from doc/shell.md rename to doc/shell.section.md diff --git a/pkgs/development/idris-modules/README.md b/pkgs/development/idris-modules/README.md index 005ed360285..80b7ccefbcf 100644 --- a/pkgs/development/idris-modules/README.md +++ b/pkgs/development/idris-modules/README.md @@ -1,39 +1 @@ -Idris packages -============== - -This directory contains build rules for idris packages. In addition, -it contains several functions to build and compose those packages. -Everything is exposed to the user via the `idrisPackages` attribute. - -callPackage ------------- - -This is like the normal nixpkgs callPackage function, specialized to -idris packages. - -builtins ---------- - -This is a list of all of the libraries that come packaged with Idris -itself. - -build-idris-package --------------------- - -A function to build an idris package. Its sole argument is a set like -you might pass to `stdenv.mkDerivation`, except `build-idris-package` -sets several attributes for you. See `build-idris-package.nix` for -details. - -build-builtin-package ----------------------- - -A version of `build-idris-package` specialized to builtin libraries. -Mostly for internal use. - -with-packages -------------- - -Bundle idris together with a list of packages. Because idris currently -only supports a single directory in its library path, you must include -all desired libraries here, including `prelude` and `base`. \ No newline at end of file +Moved to [/doc/languages-frameworks/idris.section.md](/doc/languages-frameworks/idris.section.md) diff --git a/pkgs/development/node-packages/README.md b/pkgs/development/node-packages/README.md index 17a203ed12b..9760285a915 100644 --- a/pkgs/development/node-packages/README.md +++ b/pkgs/development/node-packages/README.md @@ -1,51 +1 @@ -Node.js packages -================ -The `pkgs/development/node-packages` folder contains a generated collection of -[NPM packages](https://npmjs.com/) that can be installed with the Nix package -manager. - -As a rule of thumb, the package set should only provide *end user* software -packages, such as command-line utilities. Libraries should only be added to the -package set if there is a non-NPM package that requires it. - -When it is desired to use NPM libraries in a development project, use the -`node2nix` generator directly on the `package.json` configuration file of the -project. - -The package set also provides support for multiple Node.js versions. The policy -is that a new package should be added to the collection for the latest stable LTS -release (which is currently 6.x), unless there is an explicit reason to support -a different release. - -If your package uses native addons, you need to examine what kind of native -build system it uses. Here are some examples: - -* `node-gyp` -* `node-gyp-builder` -* `node-pre-gyp` - -After you have identified the correct system, you need to override your package -expression while adding in build system as a build input. For example, `dat` -requires `node-gyp-build`, so we override its expression in `default-v6.nix`: - -```nix -dat = nodePackages.dat.override (oldAttrs: { - buildInputs = oldAttrs.buildInputs ++ [ nodePackages.node-gyp-build ]; -}); -``` - -To add a package from NPM to nixpkgs: - - 1. Modify `pkgs/development/node-packages/node-packages-v6.json` to add, update - or remove package entries. (Or `pkgs/development/node-packages/node-packages-v4.json` - for packages depending on Node.js 4.x) - 2. Run the script: `(cd pkgs/development/node-packages && ./generate.sh)`. - 3. Build your new package to test your changes: - `cd /path/to/nixpkgs && nix-build -A nodePackages.`. - To build against a specific Node.js version (e.g. 4.x): - `nix-build -A nodePackages_4_x.` - 4. Add and commit all modified and generated files. - -For more information about the generation process, consult the -[README.md](https://github.com/svanderburg/node2nix) file of the `node2nix` -tool. +Moved to [/doc/languages-frameworks/node.section.md](/doc/languages-frameworks/node.section.md) diff --git a/pkgs/development/r-modules/README.md b/pkgs/development/r-modules/README.md index c8f02bd1478..e6fd09d7647 100644 --- a/pkgs/development/r-modules/README.md +++ b/pkgs/development/r-modules/README.md @@ -1,120 +1 @@ -R packages -========== - -## Installation - -Define an environment for R that contains all the libraries that you'd like to -use by adding the following snippet to your $HOME/.config/nixpkgs/config.nix file: - -```nix -{ - packageOverrides = super: let self = super.pkgs; in - { - - rEnv = super.rWrapper.override { - packages = with self.rPackages; [ - devtools - ggplot2 - reshape2 - yaml - optparse - ]; - }; - }; -} -``` - -Then you can use `nix-env -f "" -iA rEnv` to install it into your user -profile. The set of available libraries can be discovered by running the -command `nix-env -f "" -qaP -A rPackages`. The first column from that -output is the name that has to be passed to rWrapper in the code snipped above. - -However, if you'd like to add a file to your project source to make the -environment available for other contributors, you can create a `default.nix` -file like so: -```nix -let - pkgs = import {}; - stdenv = pkgs.stdenv; -in with pkgs; { - myProject = stdenv.mkDerivation { - name = "myProject"; - version = "1"; - src = if pkgs.lib.inNixShell then null else nix; - - buildInputs = with rPackages; [ - R - ggplot2 - knitr - ]; - }; -} -``` -and then run `nix-shell .` to be dropped into a shell with those packages -available. - -## RStudio - -RStudio uses a standard set of packages and ignores any custom R -environments or installed packages you may have. To create a custom -environment, see `rstudioWrapper`, which functions similarly to -`rWrapper`: - -```nix -{ - packageOverrides = super: let self = super.pkgs; in - { - - rstudioEnv = super.rstudioWrapper.override { - packages = with self.rPackages; [ - dplyr - ggplot2 - reshape2 - ]; - }; - }; -} -``` - -Then like above, `nix-env -f "" -iA rstudioEnv` will install -this into your user profile. - -Alternatively, you can create a self-contained `shell.nix` without the need to -modify any configuration files: - -```nix -{ pkgs ? import {} -}: - -pkgs.rstudioWrapper.override { - packages = with pkgs.rPackages; [ dplyr ggplot2 reshape2 ]; -} - -``` - -Executing `nix-shell` will then drop you into an environment equivalent to the -one above. If you need additional packages just add them to the list and -re-enter the shell. - -## Updating the package set - -```bash -nix-shell generate-shell.nix - -Rscript generate-r-packages.R cran > cran-packages.nix.new -mv cran-packages.nix.new cran-packages.nix - -Rscript generate-r-packages.R bioc > bioc-packages.nix.new -mv bioc-packages.nix.new bioc-packages.nix -``` - -`generate-r-packages.R ` reads `-packages.nix`, therefor the renaming. - - -## Testing if the Nix-expression could be evaluated - -```bash -nix-build test-evaluation.nix --dry-run -``` - -If this exits fine, the expression is ok. If not, you have to edit `default.nix` +Moved to [/doc/languages-frameworks/r.section.md](/doc/languages-frameworks/r.section.md) From 8c7be5927e8ba5c1925dad1d3af09624bd907116 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Sat, 24 Mar 2018 10:50:05 -0400 Subject: [PATCH 2/7] Ignore generated XML and other generated files --- doc/.gitignore | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 doc/.gitignore diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000000..d8e765e38c2 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,5 @@ +*.chapter.xml +*.section.xml +.version +out +manual-full.xml From 7e25ff7106f00bdca9957b1109e2fd9beca86ea1 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Sat, 24 Mar 2018 11:36:10 -0400 Subject: [PATCH 3/7] docs: Build with a makefile --- doc/Makefile | 69 +++++++++++++++++++++++ doc/default.nix | 129 ++++++++----------------------------------- doc/shell.section.md | 2 + 3 files changed, 95 insertions(+), 105 deletions(-) create mode 100644 doc/Makefile diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000000..366d971d781 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,69 @@ +MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./*.md ./**/*.md))) + +.PHONY: all +all: out/html/index.html out/epub/manual.epub + +.PHONY: clean +clean: + rm -f ${MD_TARGETS} .version manual-full.xml + rm -rf ./out/ + +validate: manual-full.xml + jing "$$RNG" manual-full.xml + +out/html/index.html: manual-full.xml style.css + mkdir -p out/html + xsltproc $$xsltFlags \ + --nonet --xinclude \ + --output $@ \ + "$$XSL/docbook/xhtml/docbook.xsl" \ + ./manual-full.xml + + cp ./style.css out/html/style.css + + mkdir -p out/html/images/callouts + cp "$$XSL/docbook/images/callouts/"*.gif out/html/images/callouts/ + +out/epub/manual.epub: manual-full.xml + mkdir -p out/epub/scratch + xsltproc $$xsltFlags --nonet \ + --output out/epub/scratch/ \ + "$$XSL/docbook/epub/docbook.xsl" \ + ./manual-full.xml + + cp "$$XSL/docbook/images/callouts/"*.gif out/epub/scratch/OEBPS + echo "application/epub+zip" > mimetype + zip -0Xq "out/epub/manual.epub" mimetype + rm mimetype + cd "out/epub/scratch/" && zip -Xr9D "../manual.epub" * + rm -rf "out/epub/scratch/" + +manual-full.xml: ${MD_TARGETS} .version *.xml + xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml + +.version: + nix-instantiate --eval \ + -E '(import ../lib).nixpkgsVersion' > .version + +%.section.xml: %.section.md + pandoc $^ -w docbook+smart \ + -f markdown+smart \ + | sed -e 's|||' \ + -e 's|||' \ + -e '1s| id=| xml:id=|' \ + -e '1s|\(<[^ ]* \)|\1xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" |' \ + | cat > $@ + +%.chapter.xml: %.chapter.md + pandoc $^ -w docbook+smart \ + --top-level-division=chapter \ + -f markdown+smart \ + | sed -e 's|||' \ + -e 's|||' \ + -e '1s| id=| xml:id=|' \ + -e '1s|\(<[^ ]* \)|\1|' \ + | cat > $@ diff --git a/doc/default.nix b/doc/default.nix index 1adcd796820..b04c9c1b556 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -7,116 +7,35 @@ in pkgs.stdenv.mkDerivation { name = "nixpkgs-manual"; - buildInputs = with pkgs; [ pandoc libxml2 libxslt zip ]; - xsltFlags = '' - --param section.autolabel 1 - --param section.label.includes.component.label 1 - --param html.stylesheet 'style.css' - --param xref.with.number.and.title 1 - --param toc.section.depth 3 - --param admon.style ''' - --param callout.graphics.extension '.gif' + src = ./.; + + XSL = "${pkgs.docbook5_xsl}/xml/xsl"; + RNG = "${pkgs.docbook5}/xml/rng/docbook/docbook.rng"; + xsltFlags = lib.concatStringsSep " " [ + "--param section.autolabel 1" + "--param section.label.includes.component.label 1" + "--param html.stylesheet 'style.css'" + "--param xref.with.number.and.title 1" + "--param toc.section.depth 3" + "--param admon.style ''" + "--param callout.graphics.extension '.gif'" + ]; + + postPatch = '' + echo ${lib.nixpkgsVersion} > .version ''; + installPhase = '' + dest="$out/share/doc/nixpkgs" + mkdir -p "$(dirname "$dest")" + mv out/html "$dest" + mv "$dest/index.html" "$dest/manual.html" - buildCommand = let toDocbook = { useChapters ? false, inputFile, outputFile }: - let - extraHeader = lib.optionalString (!useChapters) - ''xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" ''; - in '' - { - pandoc '${inputFile}' -w docbook+smart ${lib.optionalString useChapters "--top-level-division=chapter"} \ - -f markdown+smart \ - | sed -e 's|||' \ - -e 's|||' \ - -e '1s| id=| xml:id=|' \ - -e '1s|\(<[^ ]* \)|\1${extraHeader}|' - } > '${outputFile}' - ''; - in + mv out/epub/manual.epub "$dest/nixpkgs-manual.epub" - '' - ln -s '${sources}/'*.xml . - mkdir ./languages-frameworks - cp -s '${sources-langs}'/* ./languages-frameworks - '' - + toDocbook { - inputFile = ./introduction.chapter.md; - outputFile = "introduction.chapter.xml"; - useChapters = true; - } - + toDocbook { - inputFile = ./shell.section.md; - outputFile = "shell.section.xml"; - } - + toDocbook { - inputFile = ./languages-frameworks/python.section.md; - outputFile = "./languages-frameworks/python.section.xml"; - } - + toDocbook { - inputFile = ./languages-frameworks/haskell.section.md; - outputFile = "./languages-frameworks/haskell.section.xml"; - } - + toDocbook { - inputFile = ./languages-frameworks/idris.section.md; - outputFile = "languages-frameworks/idris.section.xml"; - } - + toDocbook { - inputFile = ./languages-frameworks/node.section.md; - outputFile = "languages-frameworks/node.section.xml"; - } - + toDocbook { - inputFile = ./languages-frameworks/r.section.md; - outputFile = "languages-frameworks/r.section.xml"; - } - + toDocbook { - inputFile = ./languages-frameworks/rust.section.md; - outputFile = "./languages-frameworks/rust.section.xml"; - } - + toDocbook { - inputFile = ./languages-frameworks/vim.section.md; - outputFile = "./languages-frameworks/vim.section.xml"; - } - + toDocbook { - inputFile = ./languages-frameworks/emscripten.section.md; - outputFile = "./languages-frameworks/emscripten.section.xml"; - } - + '' - echo ${lib.nixpkgsVersion} > .version - - # validate against relaxng schema - xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml - ${pkgs.jing}/bin/jing ${pkgs.docbook5}/xml/rng/docbook/docbook.rng manual-full.xml - - dst=$out/share/doc/nixpkgs - mkdir -p $dst - xsltproc $xsltFlags --nonet --xinclude \ - --output $dst/manual.html \ - ${pkgs.docbook5_xsl}/xml/xsl/docbook/xhtml/docbook.xsl \ - ./manual.xml - - cp ${./style.css} $dst/style.css - - mkdir -p $dst/images/callouts - cp "${pkgs.docbook5_xsl}/xml/xsl/docbook/images/callouts/"*.gif $dst/images/callouts/ - - mkdir -p $out/nix-support - echo "doc manual $dst manual.html" >> $out/nix-support/hydra-build-products - - xsltproc $xsltFlags --nonet --xinclude \ - --output $dst/epub/ \ - ${pkgs.docbook5_xsl}/xml/xsl/docbook/epub/docbook.xsl \ - ./manual.xml - - cp -r $dst/images $dst/epub/OEBPS - echo "application/epub+zip" > mimetype - manual="$dst/nixpkgs-manual.epub" - zip -0Xq "$manual" mimetype - cd $dst/epub && zip -Xr9D "$manual" * - rm -rf $dst/epub + mkdir -p $out/nix-support/ + echo "doc manual $dest manual.html" >> $out/nix-support/hydra-build-products ''; } diff --git a/doc/shell.section.md b/doc/shell.section.md index 079574d4ae8..cb8832a814f 100644 --- a/doc/shell.section.md +++ b/doc/shell.section.md @@ -4,6 +4,8 @@ author: zimbatm date: 2017-10-30 --- +# mkShell + pkgs.mkShell is a special kind of derivation that is only useful when using it combined with nix-shell. It will in fact fail to instantiate when invoked with nix-build. From f67ea4a6d0b14a61af3ccd98ef1a37ce870162e1 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Sat, 24 Mar 2018 22:10:55 -0400 Subject: [PATCH 4/7] Document shell.nix / xmloscopy / make for the nixpkgs docs --- doc/contributing.xml | 24 ++++++++++++++++++++---- doc/shell.nix | 4 ++++ 2 files changed, 24 insertions(+), 4 deletions(-) create mode 100644 doc/shell.nix diff --git a/doc/contributing.xml b/doc/contributing.xml index a83059aa36e..8eed9c5416e 100644 --- a/doc/contributing.xml +++ b/doc/contributing.xml @@ -6,12 +6,28 @@ The DocBook sources of the Nixpkgs manual are in the doc -subdirectory of the Nixpkgs repository. If you make modifications to -the manual, it's important to build it before committing. You can do that as follows: +subdirectory of the Nixpkgs repository. + +You can quickly check your edits with make: -$ cd /path/to/nixpkgs -$ nix-build doc + $ cd /path/to/nixpkgs/doc + $ nix-shell + [nix-shell]$ make + + +If you experience problems, run xmloscopy --docbook5 +./manual.xml ./manual-full.xml inside the nix-shell to help +understand the docbook errors. + +After making modifications to the manual, it's important to +build it before committing. You can do that as follows: + + + $ cd /path/to/nixpkgs/doc + $ nix-shell + [nix-shell]$ make clean + [nix-shell]$ nix-build . If the build succeeds, the manual will be in diff --git a/doc/shell.nix b/doc/shell.nix new file mode 100644 index 00000000000..22590142ee1 --- /dev/null +++ b/doc/shell.nix @@ -0,0 +1,4 @@ +{ pkgs ? import ../. {} }: +(import ./default.nix).overrideAttrs (x: { + buildInputs = x.buildInputs ++ [ pkgs.xmloscopy ]; +}) From 30dd2d3feb6d872372ee6f9ec86e58c3367589c7 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Sat, 24 Mar 2018 22:22:38 -0400 Subject: [PATCH 5/7] Validate when building outputs --- doc/Makefile | 4 ++-- doc/default.nix | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 366d971d781..1ef668528ad 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -11,7 +11,7 @@ clean: validate: manual-full.xml jing "$$RNG" manual-full.xml -out/html/index.html: manual-full.xml style.css +out/html/index.html: validate manual-full.xml style.css mkdir -p out/html xsltproc $$xsltFlags \ --nonet --xinclude \ @@ -24,7 +24,7 @@ out/html/index.html: manual-full.xml style.css mkdir -p out/html/images/callouts cp "$$XSL/docbook/images/callouts/"*.gif out/html/images/callouts/ -out/epub/manual.epub: manual-full.xml +out/epub/manual.epub: validate manual-full.xml mkdir -p out/epub/scratch xsltproc $$xsltFlags --nonet \ --output out/epub/scratch/ \ diff --git a/doc/default.nix b/doc/default.nix index b04c9c1b556..5869920415c 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -7,7 +7,7 @@ in pkgs.stdenv.mkDerivation { name = "nixpkgs-manual"; - buildInputs = with pkgs; [ pandoc libxml2 libxslt zip ]; + buildInputs = with pkgs; [ pandoc libxml2 libxslt zip jing ]; src = ./.; From fce1fb7e7573cacfd3edaa282cb4ebdcb58d6681 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Sun, 25 Mar 2018 07:37:41 -0400 Subject: [PATCH 6/7] Move validate to top-level so it doesn't rebuild the outputs every time --- doc/Makefile | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 1ef668528ad..f3a4d6b5aaf 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,17 +1,18 @@ MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./*.md ./**/*.md))) .PHONY: all -all: out/html/index.html out/epub/manual.epub +all: validate out/html/index.html out/epub/manual.epub .PHONY: clean clean: rm -f ${MD_TARGETS} .version manual-full.xml rm -rf ./out/ +.PHONY: validate validate: manual-full.xml jing "$$RNG" manual-full.xml -out/html/index.html: validate manual-full.xml style.css +out/html/index.html: manual-full.xml style.css mkdir -p out/html xsltproc $$xsltFlags \ --nonet --xinclude \ @@ -23,8 +24,9 @@ out/html/index.html: validate manual-full.xml style.css mkdir -p out/html/images/callouts cp "$$XSL/docbook/images/callouts/"*.gif out/html/images/callouts/ + chmod u+w -R out/html/images/ -out/epub/manual.epub: validate manual-full.xml +out/epub/manual.epub: manual-full.xml mkdir -p out/epub/scratch xsltproc $$xsltFlags --nonet \ --output out/epub/scratch/ \ From 67f9d2425dedbea2c2611100a6fb5935de9a6123 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Sun, 25 Mar 2018 20:01:31 -0400 Subject: [PATCH 7/7] Add 'make debug' to call xmloscopy --- doc/Makefile | 3 +++ doc/contributing.xml | 5 ++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index f3a4d6b5aaf..52d1f4630a8 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -3,6 +3,9 @@ MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./*.md ./**/*.md))) .PHONY: all all: validate out/html/index.html out/epub/manual.epub +.PHONY: debug +debug: + nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml" .PHONY: clean clean: rm -f ${MD_TARGETS} .version manual-full.xml diff --git a/doc/contributing.xml b/doc/contributing.xml index 8eed9c5416e..7aa0df271ff 100644 --- a/doc/contributing.xml +++ b/doc/contributing.xml @@ -16,9 +16,8 @@ subdirectory of the Nixpkgs repository. [nix-shell]$ make -If you experience problems, run xmloscopy --docbook5 -./manual.xml ./manual-full.xml inside the nix-shell to help -understand the docbook errors. +If you experience problems, run make debug +to help understand the docbook errors. After making modifications to the manual, it's important to build it before committing. You can do that as follows: