nixpkgs/doc/Makefile

MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./*.md ./**/*.md)))

.PHONY: all
all: validate format out/html/index.html out/epub/manual.epub

.PHONY: debug
debug:
	nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"

.PHONY: format
format:
	find . -iname '*.xml' -type f | while read f; do \
		echo $$f ;\
		xmlformat --config-file "$$XMLFORMAT_CONFIG" -i $$f ;\
	done

.PHONY: fix-misc-xml
fix-misc-xml:
	find . -iname '*.xml' -type f \
		-exec ../nixos/doc/varlistentry-fixer.rb {} ';'

.PHONY: clean
clean:
	rm -f ${MD_TARGETS} .version manual-full.xml functions/library/locations.xml functions/library/generated
	rm -rf ./out/ ./highlightjs

.PHONY: validate
validate: manual-full.xml
	jing "$$RNG" manual-full.xml

out/html/index.html: manual-full.xml style.css highlightjs
	mkdir -p out/html
	xsltproc ${xsltFlags} \
		--nonet --xinclude \
		--output $@ \
		"$$XSL/docbook/xhtml/docbook.xsl" \
		./manual-full.xml

	mkdir -p out/html/highlightjs/
	cp -r highlightjs out/html/

	cp ./overrides.css out/html/
	cp ./style.css out/html/style.css

	mkdir -p out/html/images/callouts
	cp "$$XSL/docbook/images/callouts/"*.svg out/html/images/callouts/
	chmod u+w -R out/html/

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 ./overrides.css out/epub/scratch/OEBPS
	cp ./style.css out/epub/scratch/OEBPS
	mkdir -p out/epub/scratch/OEBPS/images/callouts/
	cp "$$XSL/docbook/images/callouts/"*.svg out/epub/scratch/OEBPS/images/callouts/
	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/"

highlightjs:
	mkdir -p highlightjs
	cp -r "$$HIGHLIGHTJS/highlight.pack.js" highlightjs/
	cp -r "$$HIGHLIGHTJS/LICENSE" highlightjs/
	cp -r "$$HIGHLIGHTJS/mono-blue.css" highlightjs/
	cp -r "$$HIGHLIGHTJS/loader.js" highlightjs/


manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml functions/library/generated *.xml **/*.xml **/**/*.xml
	xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml

.version:
	nix-instantiate --eval \
		-E '(import ../lib).version' > .version

functions/library/locations.xml:
	nix-build ./lib-function-locations.nix \
		--out-link $@

functions/library/generated: functions/library/locations.xml
	nix-build ./lib-function-docs.nix \
		--arg locationsXml $< \
		--out-link $@

%.section.xml: %.section.md
	pandoc $^ -w docbook+smart \
		-f markdown+smart \
	  | sed -e 's|<ulink url=|<link xlink:href=|' \
	      -e 's|</ulink>|</link>|' \
	      -e 's|<sect. id=|<section xml:id=|' \
	      -e 's|</sect[0-9]>|</section>|' \
	      -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|<ulink url=|<link xlink:href=|' \
	      -e 's|</ulink>|</link>|' \
	      -e 's|<sect. id=|<section xml:id=|' \
	      -e 's|</sect[0-9]>|</section>|' \
	      -e '1s| id=| xml:id=|' \
	      -e '1s|\(<[^ ]* \)|\1|' \
	| cat  > $@
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./.md .//.md)))`

			`.PHONY: all`
nixpkgs doc: add format Make target 2018-05-01 03:35:54 +01:00			`all: validate format out/html/index.html out/epub/manual.epub`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00
Add 'make debug' to call xmloscopy 2018-03-26 01:01:31 +01:00			`.PHONY: debug`
			`debug:`
			`nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"`
nixpkgs docs: syntax highlight 2018-03-26 13:24:27 +01:00
nixpkgs doc: add format Make target 2018-05-01 03:35:54 +01:00			`.PHONY: format`
			`format:`
manual: document ways of obtaining source hashes ... and security nuances 2019-01-10 21:15:23 +00:00			`find . -iname '*.xml' -type f \| while read f; do \`
			`echo $$f ;\`
			`xmlformat --config-file "$$XMLFORMAT_CONFIG" -i $$f ;\`
			`done`
nixpkgs doc: add format Make target 2018-05-01 03:35:54 +01:00
doc: Adds xml fixing script. (see previous and next commits) This script is used to automatically fix issues within xml documentation files. The script is for now intended to be used ad-hoc, and the commits to be examined. A future discussion will define whether: * This commit and scripts are kept. * The script is extended for common use. The biggest issue right now with the script is that it could in theory destroy a valid space-less varlistentry. The script could, in practical use, be changed and extended to normalize some parts of the XML files, mainly: * A common quoting style for attributes * Fix-up some weird formatting automatically that xmlformat doesn't catch 2018-06-01 01:26:27 +01:00			`.PHONY: fix-misc-xml`
			`fix-misc-xml:`
			`find . -iname '*.xml' -type f \`
			`-exec ../nixos/doc/varlistentry-fixer.rb {} ';'`

docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`.PHONY: clean`
			`clean:`
doc: Include function doc generation in Makefile Since #53055 was merged the Makefile for the manual could not be run correctly as the generated function documentation was included, but not actually generated. This adds the necessary generation step by first building the XML file containing function locations and preserving its store path in a variable, which is then used both for linking of the locations file and as a build input for the function docs generator. This fixes #55014 2019-02-01 10:45:30 +00:00			`rm -f ${MD_TARGETS} .version manual-full.xml functions/library/locations.xml functions/library/generated`
nixpkgs docs: syntax highlight 2018-03-26 13:24:27 +01:00			`rm -rf ./out/ ./highlightjs`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00
Move validate to top-level so it doesn't rebuild the outputs every time 2018-03-25 12:37:41 +01:00			`.PHONY: validate`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`validate: manual-full.xml`
			`jing "$$RNG" manual-full.xml`

nixpkgs docs: syntax highlight 2018-03-26 13:24:27 +01:00			`out/html/index.html: manual-full.xml style.css highlightjs`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`mkdir -p out/html`
nixpkgs docs: Use SVGs for callouts 2018-03-26 19:04:19 +01:00			`xsltproc ${xsltFlags} \`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`--nonet --xinclude \`
			`--output $@ \`
			`"$$XSL/docbook/xhtml/docbook.xsl" \`
			`./manual-full.xml`

nixpkgs docs: syntax highlight 2018-03-26 13:24:27 +01:00			`mkdir -p out/html/highlightjs/`
			`cp -r highlightjs out/html/`

Move the overridden CSS to overrides.css which can be applied on nixos.org 2018-03-26 19:45:00 +01:00			`cp ./overrides.css out/html/`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`cp ./style.css out/html/style.css`

			`mkdir -p out/html/images/callouts`
nixpkgs docs: Use SVGs for callouts 2018-03-26 19:04:19 +01:00			`cp "$$XSL/docbook/images/callouts/"*.svg out/html/images/callouts/`
nixpkgs docs: syntax highlight 2018-03-26 13:24:27 +01:00			`chmod u+w -R out/html/`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00
Move validate to top-level so it doesn't rebuild the outputs every time 2018-03-25 12:37:41 +01:00			`out/epub/manual.epub: manual-full.xml`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`mkdir -p out/epub/scratch`
nixpkgs docs: Use SVGs for callouts 2018-03-26 19:04:19 +01:00			`xsltproc ${xsltFlags} --nonet \`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`--output out/epub/scratch/ \`
			`"$$XSL/docbook/epub/docbook.xsl" \`
			`./manual-full.xml`

Move the overridden CSS to overrides.css which can be applied on nixos.org 2018-03-26 19:45:00 +01:00			`cp ./overrides.css out/epub/scratch/OEBPS`
nixpkgs docs: Use SVGs for callouts 2018-03-26 19:04:19 +01:00			`cp ./style.css out/epub/scratch/OEBPS`
			`mkdir -p out/epub/scratch/OEBPS/images/callouts/`
			`cp "$$XSL/docbook/images/callouts/"*.svg out/epub/scratch/OEBPS/images/callouts/`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`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/"`

nixpkgs docs: syntax highlight 2018-03-26 13:24:27 +01:00			`highlightjs:`
			`mkdir -p highlightjs`
			`cp -r "$$HIGHLIGHTJS/highlight.pack.js" highlightjs/`
			`cp -r "$$HIGHLIGHTJS/LICENSE" highlightjs/`
			`cp -r "$$HIGHLIGHTJS/mono-blue.css" highlightjs/`
nixos docs: syntax highlight - Rectifies diverging CSS by combining nixos/nixpkgs docs CSS - Moves our custom Highlight.js loader in to the hljs package - Switches the nixos docs to use SVG callouts too 2018-04-05 12:54:01 +01:00			`cp -r "$$HIGHLIGHTJS/loader.js" highlightjs/`
nixpkgs docs: syntax highlight 2018-03-26 13:24:27 +01:00

doc: Include function doc generation in Makefile Since #53055 was merged the Makefile for the manual could not be run correctly as the generated function documentation was included, but not actually generated. This adds the necessary generation step by first building the XML file containing function locations and preserving its store path in a variable, which is then used both for linking of the locations file and as a build input for the function docs generator. This fixes #55014 2019-02-01 10:45:30 +00:00			`manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml functions/library/generated .xml /.xml //*.xml`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml`

			`.version:`
			`nix-instantiate --eval \`
treewide: rename version attributes As suggested in https://github.com/NixOS/nixpkgs/pull/39416#discussion_r183845745 the versioning attributes in `lib` should be consistent to `nixos/version` which implicates the following changes: * `lib.trivial.version` -> `lib.trivial.release` * `lib.trivial.suffix` -> `lib.trivial.versionSuffix` * `lib.nixpkgsVersion` -> `lib.version` As `lib.nixpkgsVersion` is referenced several times in `NixOS/nixpkgs`, `NixOS/nix` and probably several user's setups. As the rename will cause a notable impact it's better to keep `lib.nixpkgsVersion` as alias with a warning yielded by `builtins.trace`. 2018-04-26 09:31:05 +01:00			`-E '(import ../lib).version' > .version`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00
Generate links to function definitions Hydra passes the full revision in to the input, which we pass through. If we don't get this ,we try to get it from other sources, or default to master which should have the definition in a close-ish location. All published docs should have theURL resolve properly, only local hackers will have the link break. 2018-10-05 15:46:58 +01:00			`functions/library/locations.xml:`
manual: Make sure building doesn't need recursive nix $(shell ...) looks a little sketch like it will be run no matter what. And there are problems building the manual on darwin so hopefully this fixes them. 2019-03-24 20:06:59 +00:00			`nix-build ./lib-function-locations.nix \`
			`--out-link $@`
doc: Include function doc generation in Makefile Since #53055 was merged the Makefile for the manual could not be run correctly as the generated function documentation was included, but not actually generated. This adds the necessary generation step by first building the XML file containing function locations and preserving its store path in a variable, which is then used both for linking of the locations file and as a build input for the function docs generator. This fixes #55014 2019-02-01 10:45:30 +00:00
manual: Make sure building doesn't need recursive nix $(shell ...) looks a little sketch like it will be run no matter what. And there are problems building the manual on darwin so hopefully this fixes them. 2019-03-24 20:06:59 +00:00			`functions/library/generated: functions/library/locations.xml`
doc: Include function doc generation in Makefile Since #53055 was merged the Makefile for the manual could not be run correctly as the generated function documentation was included, but not actually generated. This adds the necessary generation step by first building the XML file containing function locations and preserving its store path in a variable, which is then used both for linking of the locations file and as a build input for the function docs generator. This fixes #55014 2019-02-01 10:45:30 +00:00			`nix-build ./lib-function-docs.nix \`
manual: Make sure building doesn't need recursive nix $(shell ...) looks a little sketch like it will be run no matter what. And there are problems building the manual on darwin so hopefully this fixes them. 2019-03-24 20:06:59 +00:00			`--arg locationsXml $< \`
			`--out-link $@`
Generate links to function definitions Hydra passes the full revision in to the input, which we pass through. If we don't get this ,we try to get it from other sources, or default to master which should have the definition in a close-ish location. All published docs should have theURL resolve properly, only local hackers will have the link break. 2018-10-05 15:46:58 +01:00
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`%.section.xml: %.section.md`
			`pandoc $^ -w docbook+smart \`
			`-f markdown+smart \`
			`\| sed -e 's\|<ulink url=\|<link xlink:href=\|' \`
			`-e 's\|</ulink>\|</link>\|' \`
			`-e 's\|<sect. id=\|<section xml:id=\|' \`
			`-e 's\|</sect[0-9]>\|</section>\|' \`
			`-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\|<ulink url=\|<link xlink:href=\|' \`
			`-e 's\|</ulink>\|</link>\|' \`
			`-e 's\|<sect. id=\|<section xml:id=\|' \`
			`-e 's\|</sect[0-9]>\|</section>\|' \`
			`-e '1s\| id=\| xml:id=\|' \`
			`-e '1s\|\(<[^ ]* \)\|\1\|' \`
			`\| cat > $@`