Start transition to quartodoc

[juliasilge]

@machow I am seeing this error when I try to run quartodoc build, and I'm not sure what I changed since it was working earlier:

TypeError: dataclass_transform() got an unexpected keyword argument 'field_specifiers'

Does that look familiar?

Edited to say this was the version of Pydantic. I think I ran into this after installing from the dev requirements.txt in this package.

[machow]

@juliasilge I think ipython 8.13 dropped support for python 3.8, so we would need to install 8.12

https://ipython.readthedocs.io/en/stable/whatsnew/version8.html#ipython-8-12-1

[juliasilge]

@machow If I install ipython 8.12.0 locally, then doing pip-compile --extra=doc --extra=test --output-file=- setup.cfg still puts 8.13.2 into requirements/dev.txt. I think it must be something else in setup.cfg that is causing that version of ipython to be chosen.

• How do I find out what is choosing that newer version of ipython?
• Or would it be appropriate for me to use something like ipython<=8.12.0 in setup.cfg? Would I put that under "docs"?

Edited to say that this works 🎉 but quartodoc requires 3.9 or higher. I bumped the Python version to 3.9 for the remaining failing checks. ⤵️

[juliasilge]

I did not add any links to things like fsspec.filesystem because there is not much available.

[juliasilge]

This is looking pretty good, I think!

@machow here are some blockers to moving forward at this point:

🎯 When using interlinking, the generated links look like regular text instead of code:

We need them to look like [`board_folder()`](/reference/board_folder.html)

🎯 I'm having trouble using interlinks for parameters:

[juliasilge]

Will close #186 if we can get interlinks to look OK

[machow]

Shoot--I think that not generating a link inside the parameter description is a bug. We currently sanitize the output, so that symbols like | won't break the markdown table, but this ends up also screwing up the interlink syntax...

Opened an issue here https://github.com/machow/quartodoc/issues/172

[machow]

@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:

• What's a function, and what's a method? Reading pin_list() on the page makes it feel like it's a top level function. At the same time, writing it as BaseBoard.pin_list() feels a bit cumbersome. I wonder if us naming the section "Pin Methods" might help? But overall think it's a very useful area to discuss, since it lives in that funky "translating pkgdown to python" space.
• It feels like something is missing to see constructors like board_s3() but not a board object like BaseBoard listed. In the original docs I just stuffed it in with the methods. We can use quartodoc to create a similar BaseBoard page if we want. I'm still trying to get a feel for the right move in these kinds of situations. For vetiver we include the class VetiverAPI on the reference page, along with its methods).

Here's the relevant BaseBoard page on the current pins docs

edit: here's how vetiver lays out the class and methods on the reference page

[juliasilge]

@machow So great to see those changes integrated!

• I added descriptions to say that we have "Constructors for board objects" and then "Pin methods for your board".
• I feel fuzzy on what adding documentation for BaseBoard gets us that isn't already there in the sidebar. Can you tell me a little bit more about what we might document on a page like that?
• One more question on formatting -- how can we get the links on this page to be code where appropriate, i.e. board_folder and not "board_folder" in regular text?

[machow]

I feel fuzzy on what adding documentation for BaseBoard gets us that isn't already there in the sidebar. Can you tell me a little bit more about what we might document on a page like that?

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 pin_read() lives. (On the page itself we could just emphasize that this is the main object people interact with in the package; repeat some of the other constructor stuff).

Alternatively

If 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.

[juliasilge]

• I updated the sections on the main reference index the way we chatted about @machow, to clarify that everything in the "Pins" section is a method.
• I did remove the sidebar and it's a big improvement (clearer/cleaner and less confusing). We do still have page navigation at the bottom to click through all the boards/pins pages, which I think is OK to keep (not so distracting).

[machow]

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)?

[juliasilge]

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.

[machow]

Thanks, this is super helpful feedback--especially about being in favor of removing the vetiver sidebar.

[machow]

TODO:

• change "Function Reference" to Reference
• remove dev branch of quartodoc (should be on main)

[juliasilge]

Also TODO here is to switch to the regular /docs folder, and replace the existing docs.

[machow]

Okay, finally wrapped the last TODO pieces w/ @isabelizimm , merging!