| Age | Commit message (Collapse) | Author | Files | Lines |
|---|
|
Section in the manual have been preserved with a simple redirect to
GitHub, the proper anchors should be filled out in a future commit once
the new section names are decided.
|
|
fix outdated contributing to documentation
|
|
Co-authored-by: Jan Tojnar <jtojnar@gmail.com>
|
|
doc syntax section into chapter, link from nixos manual
|
|
Co-authored-by: Shahar "Dawn" Or <mightyiampresence@gmail.com>
|
|
doc/contributing: update build instructions after nrd
|
|
We have moved away from Make since nixos-render-docs was introduced to
build the nixpkgs manual in #239636.
|
|
Co-authored-by: Alejandro Sanchez Medina <alejandrosanchzmedina@gmail.com>
|
|
Co-authored-by: Shahar "Dawn" Or <mightyiampresence@gmail.com>
|
|
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).
|
|
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.
|
|
both of these render distinctly from plain literals in the manpage, and
manpages even semantically distinguish between the two.
|
|
|
|
|
|
|
|
Officially, only the manpage role is supported at the moment.
Unlike in rST, the syntax uses braces instead of colons:
{manpage}`nix.conf(5)`
|
|
Syntax is taken from MyST:
https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing
|
|
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.
|
|
Not depicted:
- Diagrams using Lua filter and dot
- fenced code attributes (enabled by the attributes extension)
|
|
When running make manually, makeFlags will not be passed. Let’s just use an environment variable.
|
|
|
