I354 cpp docs #355
I354 cpp docs #355
Conversation
Codecov Report
@@ Coverage Diff @@
## master #355 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 64 64
Lines 3508 3506 -2
=========================================
- Hits 3508 3506 -2
Continue to review full report at Codecov.
|
.github/workflows/pkgdown.yaml
Outdated
| branches: | ||
| - master | ||
| - main | ||
| - i354-cpp-docs |
There was a problem hiding this comment.
possibly remove this before merging
| @@ -35,6 +35,8 @@ And several on the random number generator, around which dust is built: | |||
| * `vignette("rng_algorithms")` on the details of algorithms used to sample from some distributions | |||
| * `vignette("rng_package")` on using the generators from other packages | |||
|
|
|||
| The C++ API is documented in a separate [set of documentation](cpp) | |||
There was a problem hiding this comment.
If possible, this link going in one of the drop-down menus in the R docs would be very helpful for its discoverability I think
There was a problem hiding this comment.
yeah, that's not going to be possible with this setup. As I was writing a blog post though I thought of a better way, and will implement that after. It will remove sphinx and breathe entirely from this system and create a set of additional markdown files that should easily be incorporated into the usual doc structure
developing.md
Outdated
| There are lots of places to consider putting documentation | ||
|
|
||
| * Following R package standards, all user facing functions must be documented and have examples, we use roxygen for this (generates files in `man/`). However, because most of the work in dust | ||
| * Vignettes form the backbone of the documentation. Mostof these are directly built as normal (in `vignettes/`) but a few are precomputed (see [`vignettes_src/`](vignette_src)) where they need special resources such as access to a GPU |
There was a problem hiding this comment.
| * Vignettes form the backbone of the documentation. Mostof these are directly built as normal (in `vignettes/`) but a few are precomputed (see [`vignettes_src/`](vignette_src)) where they need special resources such as access to a GPU | |
| * Vignettes form the backbone of the documentation. Mostof these are directly built as normal (in `vignettes/`) but a few are precomputed (see [`vignettes_src/`](vignette_src)) where they need special resources such as access to a GPU or using many cores. |
developing.md
Outdated
|
|
||
| There are lots of places to consider putting documentation | ||
|
|
||
| * Following R package standards, all user facing functions must be documented and have examples, we use roxygen for this (generates files in `man/`). However, because most of the work in dust |
There was a problem hiding this comment.
Partial sentence at the end here?
There was a problem hiding this comment.
no idea what that was going to say
sphinx/random-state.rst
Outdated
| .. doxygenenum:: dust::random::scrambler | ||
|
|
||
|
|
||
| Concrete types |
There was a problem hiding this comment.
https://www.dcpu1.com/blog/different-types-of-concrete/?
Maybe something like 'Random number generator algorithms'
| @@ -51,7 +51,7 @@ and then run it with | |||
|
|
|||
| ```r | |||
| pi_r(1e6) | |||
| #> [1] 3.139764 | |||
| #> [1] 3.139504 | |||
There was a problem hiding this comment.
I enjoy that pi changes with every re-run, which confuses me when I first see it
Co-authored-by: John Lees <[email protected]>
This PR starts the process of documenting the C++ interface, which was getting increasingly awkward to do from vignettes.
There's quite an exciting system for creating automatic examples, but I think it works pretty well. It's possible that either sphinx or doxygen supports this more natively but it's not obvious to me.
The main outstanding pain now is that it would be (much) nicer if we could sort out getting sphinx to inherit the pkgdown theme. That might not be that hard to do given they're both bootstrap based, but I'm not giving it a try yet.
Lots of points of improvements in the docs I expect, but I believe I've captured the key bits. We'll need to add another round here for the GPU interface probably, and I was thinking that the main dust objects would benefit from one too before starting on any python interface (#271). However, that can wait too.
Once this is up I will describe it in a blog post. Much of this approach came from this blog post.
Other things that snuck in while being documented:
import_statemethod inprngwas unnecessarily general and I've tidied that upThe nominally excessive size is due to the crazy default Doxyfile - I had a quick go at hacking it down but broke things on the first attempt. I'll probably have another go tomorrow but that should not hold anything else upAnother attempt and we've got a sensible size Doxyfile nowFixes #354