doc/Makefile

   1 MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$' -not -name README.md)))
   2
   3 PANDOC ?= pandoc
   4
   5 pandoc_media_dir = media
   6 # NOTE: Keep in sync with NixOS manual (/nixos/doc/manual/md-to-db.sh) and conversion script (/maintainers/scripts/db-to-md.sh).
   7 # TODO: Remove raw-attribute when we can get rid of DocBook altogether.
   8 pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
   9 # Not needed:
  10 # - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)
  11 pandoc_flags = --extract-media=$(pandoc_media_dir) \
  12         --lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
  13         --lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \
  14         --lua-filter=build-aux/pandoc-filters/link-unix-man-references.lua \
  15         --lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
  16         --lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \
  17         -f commonmark$(pandoc_commonmark_enabled_extensions)+smart
  18
  19 .PHONY: all
  20 all: validate format out/html/index.html out/epub/manual.epub
  21
  22 .PHONY: debug
  23 debug:
  24         nix-shell --run "xmloscopy --docbook5 ./manual.xml ./manual-full.xml"
  25
  26 .PHONY: format
  27 format: doc-support/result
  28         find . -iname '*.xml' -type f | while read f; do \
  29                 echo $$f ;\
  30                 xmlformat --config-file "doc-support/result/xmlformat.conf" -i $$f ;\
  31         done
  32
  33 .PHONY: fix-misc-xml
  34 fix-misc-xml:
  35         find . -iname '*.xml' -type f \
  36                 -exec ../nixos/doc/varlistentry-fixer.rb {} ';'
  37
  38 .PHONY: clean
  39 clean:
  40         rm -f ${MD_TARGETS} doc-support/result .version manual-full.xml functions/library/locations.xml functions/library/generated
  41         rm -rf ./out/ ./highlightjs ./media
  42
  43 .PHONY: validate
  44 validate: manual-full.xml doc-support/result
  45         jing doc-support/result/docbook.rng manual-full.xml
  46
  47 out/html/index.html: doc-support/result manual-full.xml style.css highlightjs
  48         mkdir -p out/html
  49         xsltproc \
  50                 --nonet --xinclude \
  51                 --output $@ \
  52                 doc-support/result/xhtml.xsl \
  53                 ./manual-full.xml
  54
  55         mkdir -p out/html/highlightjs/
  56         cp -r highlightjs out/html/
  57
  58         cp -r $(pandoc_media_dir) out/html/
  59         cp ./overrides.css out/html/
  60         cp ./style.css out/html/style.css
  61
  62         mkdir -p out/html/images/callouts
  63         cp doc-support/result/xsl/docbook/images/callouts/*.svg out/html/images/callouts/
  64         chmod u+w -R out/html/
  65
  66 out/epub/manual.epub: manual-full.xml
  67         mkdir -p out/epub/scratch
  68         xsltproc --nonet \
  69                 --output out/epub/scratch/ \
  70                 doc-support/result/epub.xsl \
  71                 ./manual-full.xml
  72
  73         cp -r $(pandoc_media_dir) out/epub/scratch/OEBPS
  74         cp ./overrides.css out/epub/scratch/OEBPS
  75         cp ./style.css out/epub/scratch/OEBPS
  76         mkdir -p out/epub/scratch/OEBPS/images/callouts/
  77         cp doc-support/result/xsl/docbook/images/callouts/*.svg out/epub/scratch/OEBPS/images/callouts/
  78         echo "application/epub+zip" > mimetype
  79         zip -0Xq "out/epub/manual.epub" mimetype
  80         rm mimetype
  81         cd "out/epub/scratch/" && zip -Xr9D "../manual.epub" *
  82         rm -rf "out/epub/scratch/"
  83
  84 highlightjs: doc-support/result
  85         mkdir -p highlightjs
  86         cp -r doc-support/result/highlightjs/highlight.pack.js highlightjs/
  87         cp -r doc-support/result/highlightjs/LICENSE highlightjs/
  88         cp -r doc-support/result/highlightjs/mono-blue.css highlightjs/
  89         cp -r doc-support/result/highlightjs/loader.js highlightjs/
  90
  91
  92 manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml functions/library/generated *.xml **/*.xml **/**/*.xml
  93         xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
  94
  95 .version: doc-support/result
  96         ln -rfs ./doc-support/result/version .version
  97
  98 doc-support/result: doc-support/default.nix
  99         (cd doc-support; nix-build)
 100
 101 functions/library/locations.xml: doc-support/result
 102         ln -rfs ./doc-support/result/function-locations.xml functions/library/locations.xml
 103
 104 functions/library/generated: doc-support/result
 105         ln -rfs ./doc-support/result/function-docs functions/library/generated
 106
 107 %.section.xml: %.section.md
 108         $(PANDOC) $^ -t docbook \
 109                 $(pandoc_flags) \
 110                 -o $@
 111
 112 %.chapter.xml: %.chapter.md
 113         $(PANDOC) $^ -t docbook \
 114                 --top-level-division=chapter \
 115                 $(pandoc_flags) \
 116                 -o $@