doc: dedocbookify nixpkgs manual #239636
doc: dedocbookify nixpkgs manual #239636
Conversation
github-actions
bot
added
the
8.has: documentation
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-06-26-documentation-team-meeting-notes-58/29666/1 |
pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
Outdated
Show resolved
Hide resolved
docbook always emits intra-file links if only a single file is emitted. it doesn't seem to do this for intra-file links when multiple files are emitted, so we don't do that yet either.
there's not point in rendering these if we're rendering to a single file for all content.
pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
Outdated
Show resolved
Hide resolved
pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
Outdated
Show resolved
Hide resolved
the nixpkgs manual uses section tocs for eg the nixpkgs library function reference. we will only not emit tocs for subsections at this point, but maybe we should consider doing so in the future.
pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Some of these are still used by nixos-search. Can we remove them now @ncfavier, or should we wait?
There was a problem hiding this comment.
Yeah, nixos-search uses this file. I guess it should be moved into the nixos-search tree before we remove it here
|
this should have addressed all comments so far :) |
this is only used in the stdenv chapter, but footnotes could be useful in other places as well. since markdown-it has a plugin to parse footnote syntax we may as well just support them even if they're rare.
mostly to clean up the main manual build makefile and derivation a bit. not technically necessary, but will make life easier later.
nothing except function docs uses this, so we need not expose it. we'll be reworking this entire section of the build anyway, with the target of breaking up doc-support as it is now.
|
nixdoc got a release for improved markdown output, no more unstable for that :) |
also updates nixdoc to 2.3.0. the nixdoc update is not a separate commit because that would leave the manual build broken for one commit, potentially breaking bisects and rebases.
all xml-related tooling can go away. shell.nix is no longer useful since the makefile is gone and the build runs entirely via a derivation, and gitignore is thus also no longer that useful. it may filter out some swap files, but its main reason to exist (keeping generated files out of a concurrent build of the derivation) has gone away.
this leaves doc-support as a simple wrapper around function docs. this wrapper will go away very soon as well.
separating function docs out like this makes it less clear how library documentation is generated and integrated into the build. if in the future more parts of nixpkgs use nixdoc it will make sense to have all information about library doc generation in the same place.
|
ope, had left the old nixdoc homepage url by mistake. should point to the nix-community repo now instead. |
|
Reviewed together with @pennae and @asymmetric. This looks very good and we can still fix up details as we go. |
|
@ncfavier can you take care of moving the files nixos-search needs? would like to merge soon before divergences happen and we have to redo the xml-to-md bit again. |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-07-03-documentation-team-meeting-notes-60/29983/1 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/tables-or-html-in-nixpkgs-manual/29989/4 |
We have moved away from Make since nixos-render-docs was introduced to build the nixpkgs manual in NixOS#239636.
Description of changes
extend nixos-render-docs with the minal missing features needed to render the nixpkgs manual, and migrate the nixpkgs manual over. this also removes a lot of support infrastructure and the ability to build the manual in a nix shell since the build now takes all of five seconds when started from scratch. keeping the shell+makefile combo alive adds more complexity than it's worth at that kind of speed, and impure manual builds are a bit of a trap anyway.
the manual is almost completely identical except for a few heading level changes, element id changes, and nixdoc function reordering. nixdoc should probably sort its output at some point, but today is not that day.
drafted because the nixdoc update included here reference a not-yet-merged PR.
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/)