Add automatic generation of library function documentation#53055
Add automatic generation of library function documentation#53055FRidh merged 1 commit intoNixOS:masterfrom
Conversation
Modifies the build process of the manual to invoke nixdoc automatically to generate XML files with function documentation. Currently documentation is present for five of the files in `lib/`. To add another file to the generated docs, both `doc/functions/library.xml` and `doc/lib-function-docs.nix` must be updated.
tazjin
force-pushed
the
feat/automatic-lib-doc-generation
branch
from
d43bd3a to
cce24bf
Compare
GrahamcOfBorg
added
the
8.has: documentation
infinisil
left a comment
infinisil
left a comment
There was a problem hiding this comment.
I'm very much in favor of this approach. Having checked in the generated xml files wouldn't really serve any direct purpose, because they're neither nice to look at nor editable (as edits would get overridden).
GrahamcOfBorg
added
10.rebuild-darwin: 0
|
One note about this: The path for overrides will not work with this version (at the moment). That requires a change in Overrides are not actually in use yet though, so it does not matter much for now. |
FRidh
left a comment
FRidh
left a comment
There was a problem hiding this comment.
This looks very good. I think we need to update the docstrings in attrsets a bit with the info that's currently in the xml, and then we can have that one generated as well.
Currently there is a little blocker for that, As an alternative we have the override feature, where XML blobs can be dropped in to replace the documentation for a specific function - however, I can't figure out the syntax for multiple root-level elements in an override anymore. I'm sure this is something I tested with @grahamc at NixCon, so it does work - somehow. Going to have to dive into DocBook docs a little bit. |
Since #53055 was merged the Makefile for the manual could not be run correctly as the generated function documentation was included, but not actually generated. This adds the necessary generation step by first building the XML file containing function locations and preserving its store path in a variable, which is then used both for linking of the locations file and as a build input for the function docs generator. This fixes #55014
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: |
5 participants
Important: Please also see #49275. Only one of these pull requests should be merged.
cc: @infinisil @grahamc
Modifies the build process of the manual to invoke nixdoc
automatically to generate XML files with function documentation.
Currently documentation is present for five of the files in
lib/.To add another file to the generated docs, both
doc/functions/library.xmlanddoc/lib-function-docs.nixmust beupdated.