Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Add generated documentation for library functions #49275
This adds generated documentation using nixdoc for some of the library functions in
A rendered view is available for your viewing pleasure.
The documentation files can be generated by installing
Some notes & caveats:
@joachifm Eventually we'd like to do that, but as Graham mentioned the
The required features are going to stabilise not too far in the future, at which point we could add it to the automatic manual generation. An alternative approach is removing the use of unstable features from that lib and its dependencies, which @Mic92 has started doing.
Either way, for now just checking in the generated files already gets us quite far!
@jD91mZM2 Awesome, thank you! Would you consider publishing the stable-compatible
It seems like
Edit: Nevermind, managed to patch
added a commit
this pull request
Oct 28, 2018
It's ready technically, I'll just make more PRs when I cover the other files.
What do you think about this strategy for merging:
Ideally the "update generated docs" step would be a make target in the Makefile, not called by default.
Before merging the generated docs, I'd like to do a rendered display for people to look at.
Oh, I forgot to mention this - I publish rendered docs here at the moment.
Works for me. I'd make a new PR for the
For the 18.09 PR I suppose the steps are something like:
Correct? Or is that branch no longer in use?
Lets do this as the next step, we can discuss a little bit what the best workflow is but for now I just want to get Some Docs
referenced this pull request
Oct 29, 2018
Working on making it an appendix. One maybe long-term project is to fix the code examples with absolute function names, so
this might be part of a larger effort to improve the examples, though, like adding titles and splitting shared examples in to two?
Also, what is the status of splitting the input with the output, for testable doc comments?
You mean by actually updating the doc comments to look like that, or via some spooky rewriting?
It depends on me writing a proper parser for the doc comments. Currently it's a somewhat advanced string-splitter that works well with the existing format, but it should be a bit more flexible. I'll probably start looking into it this evening.