Commit Graph

13 Commits

Author SHA1 Message Date
Shahar "Dawn" Or
a064709342 nixpkgs/NixOS manuals: devmode feature
Co-authored-by: Alejandro Sanchez Medina <alejandrosanchzmedina@gmail.com>
2023-07-25 17:03:15 +07:00
pennae
0a6e6cf7e6 nixos/manual: render module chapters with nixos-render-docs
this converts meta.doc into an md pointer, not an xml pointer. since we
no longer need xml for manual chapters we can also remove support for
manual chapters from md-to-db.sh

since pandoc converts smart quotes to docbook quote elements and our
nixos-render-docs does not we lose this distinction in the rendered
output. that's probably not that bad, our stylesheet didn't make use of
this anyway (and pre-23.05 versions of the chapters didn't use quote
elements either).

also updates the nixpkgs manual to clarify that option docs support all
extensions (although it doesn't support headings at all, so heading
anchors don't work by extension).
2023-01-27 20:07:34 +01:00
Naïm Favier
a8d4cf149c
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 14:11:22 +01:00
pennae
9c3c13b50d nixos/make-options-doc: add inline roles for varname/envar
both of these render distinctly from plain literals in the manpage, and
manpages even semantically distinguish between the two.
2022-08-31 16:21:10 +02:00
pennae
320aa2a791 treewide: attempt at markdown option docs 2022-06-12 12:44:38 +02:00
Naïm Favier
8583c5f48b
doc: remove reference to unix-man-urls.lua 2021-12-28 13:26:35 +01:00
Jan Tojnar
04b59b0328 doc: Linkify man page references 2021-07-13 02:21:22 +02:00
Jan Tojnar
c9139dfa1a 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-13 02:10:57 +02:00
Jan Tojnar
3c78ad2561
doc: Use markdown syntax for xrefs
Syntax is taken from MyST:

https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing
2021-06-07 06:34:59 +02:00
Jan Tojnar
6ecc641d08
doc: prepare for commonmark
We are still using Pandoc’s Markdown parser, which differs from CommonMark spec slightly.

Notably:
- Line breaks in lists behave differently.
- Admonitions do not support the simpler syntax https://github.com/jgm/commonmark-hs/issues/75
- The auto_identifiers uses a different algorithm – I made the previous ones explicit.
- Languages (classes) of code blocks cannot contain whitespace so we have to use “pycon” alias instead of Python “console” as GitHub’s linguist

While at it, I also fixed the following issues:
- ShellSesssion was used
- Removed some pointless docbook tags.
2021-06-07 06:34:59 +02:00
Jan Tojnar
ce6b1a4f8f
doc: Document markup syntax
Not depicted:

- Diagrams using Lua filter and dot
- fenced code attributes (enabled by the attributes extension)
2021-06-06 20:05:00 +02:00
Jan Tojnar
7497b4721c doc: Fix make in nix-shell
When running make manually, makeFlags will not be passed. Let’s just use an environment variable.
2021-06-05 13:25:48 +02:00
Bobby Rong
0fd55565d3 doc/contributing/*.xml: Convert to markdown 2021-04-23 12:53:58 +08:00