-
Notifications
You must be signed in to change notification settings - Fork 12
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Start transition to quartodoc #198
Conversation
@machow
Edited to say this was the version of Pydantic. I think I ran into this after installing from the dev |
@juliasilge it looks like the latest quartodoc changes are working: the interlinks are now wrapped inside code elements, and can render in a parameter table description. One tricky thing with pins (related to figuring out analogue to pkgdown) seems like how we convey two pieces:
Here's the relevant edit: here's how vetiver lays out the class and methods on the reference page |
@machow So great to see those changes integrated!
|
It feels like some kind of connective tissue is missing. There are a bunch of function/method names on the page, but as a person who will be interacting with an object, it's surprising the object type itself is not documented / named. The idea that some functions return an object, and then some other things that look like functions are actually methods on an object--without the object there--feels like it's missing what l see in the repl / various informative displays. RE "what we might document on a page like that?" I think this situation is similar to documenting an S4 / R6 class, so just having the type name on the sidebar will reinforce where AlternativelyIf we are very loud in saying some things construct a BaseBoard instance, some things are methods, we might be able to get the point across. |
|
Thanks for these changes! Do you mind saying more about when you think removing the sidebar makes things more clear? I'm onboard with any changes, and want to make sure I capture the strategy (eg why removing the sidebar might provide clarity here compared to the vetiver api docs). It seems like the big factor might just be the size of the pins api docs (since it's just documentation around roughly a single class, with only a few methods)? |
I would likely vote for removing the sidebar on the vetiver reference page too, to make more pleasant and focused pages, but I do think for pins it's harder to argue it adds much helpful info (a small package, like you said) relative to the added visual busy-ness. The biggest challenge is that a sidebar full of either styled code (PURPLE! or GREEN! or what the theme has) or plain text ("which ones of these are words?") doesn't look very good/clear and so is distracting. Maybe in the long run, some more pleasant and subtle styling of the sidebar would be possible. |
Thanks, this is super helpful feedback--especially about being in favor of removing the vetiver sidebar. |
TODO:
|
Also TODO here is to switch to the regular |
Okay, finally wrapped the last TODO pieces w/ @isabelizimm , merging! |
No description provided.