nixpkgs/doc/Makefile

MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$' -not -name README.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: doc-support/result
	find . -iname '*.xml' -type f | while read f; do \
		echo $$f ;\
		xmlformat --config-file "doc-support/result/xmlformat.conf" -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} doc-support/result .version manual-full.xml functions/library/locations.xml functions/library/generated
	rm -rf ./out/ ./highlightjs

.PHONY: validate
validate: manual-full.xml doc-support/result
	jing doc-support/result/docbook.rng manual-full.xml

out/html/index.html: doc-support/result manual-full.xml style.css highlightjs
	mkdir -p out/html
	xsltproc \
		--nonet --xinclude \
		--output $@ \
		doc-support/result/xhtml.xsl \
		./manual-full.xml

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

	cp -r media out/html/
	cp ./overrides.css out/html/
	cp ./style.css out/html/style.css

	mkdir -p out/html/images/callouts
	cp doc-support/result/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 --nonet \
		--output out/epub/scratch/ \
		doc-support/result/epub.xsl \
		./manual-full.xml

	cp -r media out/epub/scratch/OEBPS
	cp ./overrides.css out/epub/scratch/OEBPS
	cp ./style.css out/epub/scratch/OEBPS
	mkdir -p out/epub/scratch/OEBPS/images/callouts/
	cp doc-support/result/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: doc-support/result
	mkdir -p highlightjs
	cp -r doc-support/result/highlightjs/highlight.pack.js highlightjs/
	cp -r doc-support/result/highlightjs/LICENSE highlightjs/
	cp -r doc-support/result/highlightjs/mono-blue.css highlightjs/
	cp -r doc-support/result/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: doc-support/result
	ln -rfs ./doc-support/result/version .version

doc-support/result: doc-support/default.nix
	(cd doc-support; nix-build)

functions/library/locations.xml: doc-support/result
	ln -rfs ./doc-support/result/function-locations.xml functions/library/locations.xml

functions/library/generated: doc-support/result
	ln -rfs ./doc-support/result/function-docs functions/library/generated

%.section.xml: %.section.md
	pandoc $^ -t docbook \
		--extract-media=media \
		--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
		-f markdown+smart \
	| cat  > $@

%.chapter.xml: %.chapter.md
	pandoc $^ -t docbook \
		--top-level-division=chapter \
		--extract-media=media \
		--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
		-f markdown+smart \
	| cat  > $@
doc/README.md: init 2021-03-04 16:52:32 +00:00			`MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$' -not -name README.md)))`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00
			`.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`
xmlformat.conf: move to doc-support build 2019-07-04 13:51:43 +01:00			`format: doc-support/result`
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.conf: move to doc-support build 2019-07-04 13:51:43 +01:00			`xmlformat --config-file "doc-support/result/xmlformat.conf" -i $$f ;\`
manual: document ways of obtaining source hashes ... and security nuances 2019-01-10 21:15:23 +00:00			`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:`
docs: use a single nix-build for all the generate function docs 2019-07-04 13:23:39 +01:00			`rm -f ${MD_TARGETS} doc-support/result .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: find docbook rng from doc-support 2019-07-04 13:30:13 +01:00			`validate: manual-full.xml doc-support/result`
			`jing doc-support/result/docbook.rng manual-full.xml`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00
docs: get XSL from build / symlink 2019-07-04 13:46:47 +01:00			`out/html/index.html: doc-support/result manual-full.xml style.css highlightjs`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`mkdir -p out/html`
doc: move parameters to an XML file 2019-07-04 14:06:39 +01:00			`xsltproc \`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`--nonet --xinclude \`
			`--output $@ \`
doc: move parameters to an XML file 2019-07-04 14:06:39 +01:00			`doc-support/result/xhtml.xsl \`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`./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/`

doc: Add staging workflow diagram 2020-12-05 12:47:29 +00:00			`cp -r media 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`
docs: get XSL from build / symlink 2019-07-04 13:46:47 +01:00			`cp doc-support/result/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`
doc: move parameters to an XML file 2019-07-04 14:06:39 +01:00			`xsltproc --nonet \`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`--output out/epub/scratch/ \`
doc: move parameters to an XML file 2019-07-04 14:06:39 +01:00			`doc-support/result/epub.xsl \`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`./manual-full.xml`

doc: Add staging workflow diagram 2020-12-05 12:47:29 +00:00			`cp -r media out/epub/scratch/OEBPS`
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/`
docs: get XSL from build / symlink 2019-07-04 13:46:47 +01:00			`cp doc-support/result/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/"`

docs: Get highlightjs from build symlink 2019-07-04 13:46:59 +01:00			`highlightjs: doc-support/result`
nixpkgs docs: syntax highlight 2018-03-26 13:24:27 +01:00			`mkdir -p highlightjs`
docs: Get highlightjs from build symlink 2019-07-04 13:46:59 +01:00			`cp -r doc-support/result/highlightjs/highlight.pack.js highlightjs/`
			`cp -r doc-support/result/highlightjs/LICENSE highlightjs/`
			`cp -r doc-support/result/highlightjs/mono-blue.css highlightjs/`
			`cp -r doc-support/result/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`

docs: get version from doc-support build 2019-07-04 13:27:16 +01:00			`.version: doc-support/result`
			`ln -rfs ./doc-support/result/version .version`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00
docs: get version from doc-support build 2019-07-04 13:27:16 +01:00			`doc-support/result: doc-support/default.nix`
docs: use a single nix-build for all the generate function docs 2019-07-04 13:23:39 +01:00			`(cd doc-support; nix-build)`
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
docs: use a single nix-build for all the generate function docs 2019-07-04 13:23:39 +01:00			`functions/library/locations.xml: doc-support/result`
			`ln -rfs ./doc-support/result/function-locations.xml functions/library/locations.xml`

			`functions/library/generated: doc-support/result`
			`ln -rfs ./doc-support/result/function-docs functions/library/generated`
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`
doc: clean up makefile The sectn and ulink hacks are not necessary since pandoc has been defaulting to Docbook 5 for a long time. With the pandoc patches, we can get rid of id→xml:id replacement and xmlns hacks as well. 2020-12-04 19:25:34 +00:00			`pandoc $^ -t docbook \`
doc: Add staging workflow diagram 2020-12-05 12:47:29 +00:00			`--extract-media=media \`
			`--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`-f markdown+smart \`
			`\| cat > $@`

			`%.chapter.xml: %.chapter.md`
doc: clean up makefile The sectn and ulink hacks are not necessary since pandoc has been defaulting to Docbook 5 for a long time. With the pandoc patches, we can get rid of id→xml:id replacement and xmlns hacks as well. 2020-12-04 19:25:34 +00:00			`pandoc $^ -t docbook \`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`--top-level-division=chapter \`
doc: Add staging workflow diagram 2020-12-05 12:47:29 +00:00			`--extract-media=media \`
			`--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \`
docs: Build with a makefile 2018-03-24 15:36:10 +00:00			`-f markdown+smart \`
			`\| cat > $@`