Add automatic generation of library function documentation #53055
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
|
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. |
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: |
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.