Commit graph

7 commits

Author SHA1 Message Date
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