nixos-render-docs: add support for examples #220116
Conversation
github-actions
bot
added
6.topic: nixos
ofborg
bot
added
10.rebuild-darwin: 1-10
10.rebuild-darwin: 1
10.rebuild-linux: 1-10
labels
| @@ -13,7 +13,7 @@ checking for entire option trees, it is only recommended for use in | |||
| submodules. | |||
|
|
|||
| ::: {#ex-freeform-module .example} | |||
| **Example: Freeform submodule** | |||
| ### Freeform submodule | |||
There was a problem hiding this comment.
Since the example is self-contained, could we just use # to mark the title?
There was a problem hiding this comment.
we could (and the parser will recognize it all the same), we just used three for visuals. any heading will work, including the headings with = or - underlines.
|
it's important to note that we emit not html, but xhtml. the nixos homepage (and nixos-search to some extent too, apparently) run their own xslt stylesheets on rendered manuals. we can move to html5 only once all of those have either migrated to other methods or had their specifics integrated into nrd somehow. |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-03-23-documentation-team-meeting-notes-35/26651/1 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-04-11-documentation-team-meeting-notes-40/27261/1 |
the nixos manual contains enough examples to support them as a proper toc entity with specialized rendering, and if in the future the nixpkgs wants to use nixos-render-docs we will definitely have to support them. this also allows us to restore some examples that were lost in previous translation steps because there were too few to add renderer support back then.
these examples were turned into untitle anchors previously because at the time supporting examples was not deemed necessary or useful. now that we have them we can restore them though.
|
rebased onto current master since it's been a hot minute. output still looks good, going to merge if ci passes. |
Description of changes
add support for real examples with toc entries (≍ docbook
<example>). the module chapter conversion removed a few examples that can new be restored, and the remaining manual chapters have their examples adjusted to include proper titles for toc purposes. this will also be needed if the nixpkgs manual ever decides to use nrd, its lib section is full of examples that make sense to mark up properly.Things done
sandbox = trueset innix.conf? (See Nix manual)nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage./result/bin/)