nixosOptionsDoc.optionsMarkdown: init, with anchors
#300309
Conversation
This adds a new optionsMarkdown, that's compatible with the HTML (and DocBook) outputs. This needs anchor syntax, which is not part of the CommonMark specification, as of version 0.31.2.
github-actions
bot
added
the
6.topic: nixos
ofborg
bot
added
10.rebuild-darwin: 1-10
10.rebuild-darwin: 1
10.rebuild-linux: 1-10
labels
| optionsMarkdown = pkgs.runCommand "options.md" { | ||
| nativeBuildInputs = [ pkgs.nixos-render-docs ]; | ||
| } '' | ||
| nixos-render-docs -j $NIX_BUILD_CORES options commonmark \ | ||
| --manpage-urls ${pkgs.path + "/doc/manpage-urls.json"} \ | ||
| --revision ${lib.escapeShellArg revision}${ | ||
| lib.optionalString markdownAnchors '' \ | ||
| --render-anchors \ | ||
| --anchor-prefix ${lib.escapeShellArg optionIdPrefix}''} \ | ||
| ${optionsJSON}/share/doc/nixos/options.json \ | ||
| $out | ||
| ''; |
There was a problem hiding this comment.
this mostly duplicates optionsCommonMark, it would make sense to have a function that encapsulates commonmark-plus-extensions in some way. that would also spare you the indignity of turning your own feature on while advising all other new features to be turned off.
There was a problem hiding this comment.
In #370352 I avoid this duplication by introducing extraArgs which can be overridden. That's much simpler and doesn't cause duplication.
| _id_translate_table = { | ||
| ord('*'): ord('_'), | ||
| ord('<'): ord('_'), | ||
| ord(' '): ord('_'), | ||
| ord('>'): ord('_'), | ||
| ord('['): ord('_'), | ||
| ord(']'): ord('_'), | ||
| ord(':'): ord('_'), | ||
| ord('"'): ord('_'), | ||
| } |
There was a problem hiding this comment.
that's the same table as xml uses, duplicated. it's not a great transform to begin with, we should be applying something more like url-encoding instead (but see later comments for that also).
There was a problem hiding this comment.
It now reuses that routine. I agree it's not a great transform, lacking injectivity, but it's the one that's been used all this time in DocBook and HTML option docs.
A better transform could be added by extending the enum in #370352, if anyone wants or needs that.
| @@ -437,11 +455,15 @@ def _decl_def_entry(self, href: Optional[str], name: str) -> list[str]: | |||
| def _decl_def_footer(self) -> list[str]: | |||
| return [] | |||
|
|
|||
| def make_id (self, loc: list[str]) -> str: | |||
| return '.'.join([to_id(x) for x in loc]) | |||
There was a problem hiding this comment.
that's not necessarily a unique transform any more if any module chooses to use a . in its keys. existing code gets a pass on this by virtue if being inherited bad behavior, new code should not make such mistakes if at all possible.
There was a problem hiding this comment.
Compatibility is my explicit goal with the legacy anchor style. I think I've done a good job at reusing existing code in #370352. A line of code like this is unavoidable for that. Better anchor styles can be added, as mentioned.
I agree, but I couldn't find a good place to put that function. For that I blame the structure of |
wegank
added
the
2.status: merge conflict
wegank
added
the
2.status: stale
Description of changes
This adds a new
optionsMarkdownattribute, that's compatible with the HTML (and DocBook) outputs.This functionality needs anchor syntax, which is not part of the CommonMark specification, as of version 0.31.2.
Things done
nix.conf? (See Nix manual)sandbox = relaxedsandbox = truenix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage./result/bin/)Add a 👍 reaction to pull requests you find important.