JakeHillion/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2a243b0f59
nixpkgs/doc/Makefile

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

117 lines
3.9 KiB
Makefile
Raw Normal View History

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
doc: Build as CommonMark We were using Pandoc’s Markdown parser. This is non-standard and might cause issues when we finally switch to some other tool. Since RFC 0072 agreed on CommonMark, let’s switch to that. We will use some extensions to make the limited syntax bearable but these are official so they should be more portable.
2021-06-05 20:36:48 +01:00
PANDOC ?= pandoc
pandoc_media_dir = media
nixos/manual: remove md-to-db with manual chapters no longer needing pandoc for their conversion to xml we can get rid of this source of confusion, and its huge cache of xml files.
2023-02-08 10:08:25 +00:00
# NOTE: Keep in sync with conversion script (/maintainers/scripts/db-to-md.sh).
doc: Build as CommonMark We were using Pandoc’s Markdown parser. This is non-standard and might cause issues when we finally switch to some other tool. Since RFC 0072 agreed on CommonMark, let’s switch to that. We will use some extensions to make the limited syntax bearable but these are official so they should be more portable.
2021-06-05 20:36:48 +01:00
# TODO: Remove raw-attribute when we can get rid of DocBook altogether.
pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
doc: Add support for MyST roles Officially, only the manpage role is supported at the moment. Unlike in rST, the syntax uses braces instead of colons: {manpage}`nix.conf(5)`
2021-07-12 14:54:14 +01:00
# Not needed:
# - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)
doc: Build as CommonMark We were using Pandoc’s Markdown parser. This is non-standard and might cause issues when we finally switch to some other tool. Since RFC 0072 agreed on CommonMark, let’s switch to that. We will use some extensions to make the limited syntax bearable but these are official so they should be more portable.
2021-06-05 20:36:48 +01:00
pandoc_flags = --extract-media=$(pandoc_media_dir) \
--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
doc: Add support for MyST roles Officially, only the manpage role is supported at the moment. Unlike in rST, the syntax uses braces instead of colons: {manpage}`nix.conf(5)`
2021-07-12 14:54:14 +01:00
--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \
doc: separate manpage URLs from the Pandoc filter Move the manpage-to-URL mapping to `doc/manpage-urls.json` so that we can reuse that file elsewhere, and generate the `link-manpages.lua` filter from that file. Also modify the Pandoc filter so that it doesn't wrap manpages that are already inside a link. Keeping a Lua filter is essential for speed: a Python filter would increase the runtime `md-to-db.sh` from ~20s to ~30s (but Python is not to blame; marshalling Pandoc types to and from JSON is a costly operation). Parsing in Lua seems tedious, so I went with the Nix way.
2023-01-02 13:00:58 +00:00
--lua-filter=$(PANDOC_LINK_MANPAGES_FILTER) \
doc: Add support for MyST roles Officially, only the manpage role is supported at the moment. Unlike in rST, the syntax uses braces instead of colons: {manpage}`nix.conf(5)`
2021-07-12 14:54:14 +01:00
--lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
doc: Move lua filters to subdirectory
2021-07-12 03:38:41 +01:00
--lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \
doc: Build as CommonMark We were using Pandoc’s Markdown parser. This is non-standard and might cause issues when we finally switch to some other tool. Since RFC 0072 agreed on CommonMark, let’s switch to that. We will use some extensions to make the limited syntax bearable but these are official so they should be more portable.
2021-06-05 20:36:48 +01:00
-f commonmark$(pandoc_commonmark_enabled_extensions)+smart
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
doc: Clean up generated media directory pandoc uses ./media to extract media files - add it to the list of directories that need to be removed by `make clean`.
2021-06-04 14:03:41 +01:00
rm -rf ./out/ ./highlightjs ./media
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: Build as CommonMark We were using Pandoc’s Markdown parser. This is non-standard and might cause issues when we finally switch to some other tool. Since RFC 0072 agreed on CommonMark, let’s switch to that. We will use some extensions to make the limited syntax bearable but these are official so they should be more portable.
2021-06-05 20:36:48 +01:00
cp -r $(pandoc_media_dir) 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: Build as CommonMark We were using Pandoc’s Markdown parser. This is non-standard and might cause issues when we finally switch to some other tool. Since RFC 0072 agreed on CommonMark, let’s switch to that. We will use some extensions to make the limited syntax bearable but these are official so they should be more portable.
2021-06-05 20:36:48 +01:00
cp -r $(pandoc_media_dir) 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: Build as CommonMark We were using Pandoc’s Markdown parser. This is non-standard and might cause issues when we finally switch to some other tool. Since RFC 0072 agreed on CommonMark, let’s switch to that. We will use some extensions to make the limited syntax bearable but these are official so they should be more portable.
2021-06-05 20:36:48 +01:00
$(PANDOC) $^ -t docbook \
$(pandoc_flags) \
nixos/doc: Synchronize the Markdown generator with Nixpkgs Switch to CommonMark with our extensions.
2021-06-17 23:07:00 +01:00
-o $@
docs: Build with a makefile
2018-03-24 15:36:10 +00:00
%.chapter.xml: %.chapter.md
doc: Build as CommonMark We were using Pandoc’s Markdown parser. This is non-standard and might cause issues when we finally switch to some other tool. Since RFC 0072 agreed on CommonMark, let’s switch to that. We will use some extensions to make the limited syntax bearable but these are official so they should be more portable.
2021-06-05 20:36:48 +01:00
$(PANDOC) $^ -t docbook \
docs: Build with a makefile
2018-03-24 15:36:10 +00:00
--top-level-division=chapter \
doc: Build as CommonMark We were using Pandoc’s Markdown parser. This is non-standard and might cause issues when we finally switch to some other tool. Since RFC 0072 agreed on CommonMark, let’s switch to that. We will use some extensions to make the limited syntax bearable but these are official so they should be more portable.
2021-06-05 20:36:48 +01:00
$(pandoc_flags) \
nixos/doc: Synchronize the Markdown generator with Nixpkgs Switch to CommonMark with our extensions.
2021-06-17 23:07:00 +01:00
-o $@
Reference in New Issue Copy Permalink