Fully document geoms

[rdboyes]

Fill out the docstrings for all currently supported geoms, including usage, required aes, supported optional aesthetics, and supported options

[adknudson]

I'm running into an issue where DocumenterMarkdown.jl doesn't support the latest Documenter.jl versions (v1). In fact it seems like it hasn't been touched in ~3 years. Specifically I would like to use Documenter's @docs; canonical=false feature, but that causes issues.

So I guess my discussion question is if the TidierOrg wants to continue using DocumenterMarkdown going forward? The Tidier.jl package is using DocumenterVitepress.jl which seems to be a more recent and maintained option for MkDocs.

I understand that switching all the package docs to DocumenterVitepress would be quite the undertaking (which I'd be willing to lead), but I wanted to hear some opinions first. My questions are:

1. Why does Tidier.jl use DocumenterVitepress.jl and all others use DocumenterMarkdown.jl
2. Why not use plain Documenter.jl for package docs?
3. Why use MkDocs at all?

We could follow SciML's model where they have a nice home page (source) built on Franklin.jl (Tidier.jl can continue to use Vitepress), and then their docs use plain Documenter.jl.

[kdpsingh]

@adknudson, thank you so much for asking the question. I'll share some history, my vision for ideal documentation, and potential next steps.

Back when we had just started TIdier.jl and I knew next to nothing about Julia, @lazarusA came along and helped set up documentation for the package using MkDocs. At the time, MkDocs looked more modern and stood out as compared to many of the other vanilla Documenter.jl templates, so when we expanded Tidier.jl into other packages, we stuck with the formula.

Very recently (like in the last 2 weeks), @camilogarciabotero graciously re-configured the Tidier.jl documentation to use DocumenterVitepress.jl and added some "Getting Started" pages, which looks clean, modern, and (to me) much nicer than MkDocs. So with that in mind, I'd love for us to move the other packages towards this look and feel.

My ideal documentation set-up would be a single site that contains the documentation, tutorials, and docstrings from all of the Tidier.jl packages. That is challenging to set-up because one of the ways we know that a package update via a PR didn't break anything (in addition to doctests) is to ensure that the documentation built correctly. So we will always need some amount of documentation to be specific to each base package's website.

So here's my thinking:

1. Move all Tidier packages to DocumenterVitepress.jl
2. Keep some high-level tutorials on the Tidier.jl website, with a focus on examples that rely on functionality across the packages
3. Detailed examples for base packages will sit on the package-specific docs (e.g., for TidierData, TidierPlots, etc).

This is also kind of how tidyverse.org is set up. They have a main site, with more detailed sites for each package with a consistent look and feel.

[adknudson]

@kdpsingh Thanks so much for the history and your vision. I do agree that the modern look of the docs is a win.

DocumenterVitepress.jl and added some "Getting Started" pages, which looks clean, modern, and (to me) much nicer than MkDocs. So with that in mind, I'd love for us to move the other packages towards this look and feel.

Happy to start this process with TidierPlots. Perhaps @camilogarciabotero and I can coordinate for updating all the packages. Can an issue be opened on the Tidier.jl repo listing all the packages that need updating do DocumenterVitepress.jl?

My ideal documentation set-up would be a single site that contains the documentation, tutorials, and docstrings from all of the Tidier.jl packages.

Are there any examples of Julia package ecosystems that already do this? I'm not even sure if SciML does something like this and I consider them one of the gold standards for package and documentation development.

So here's my thinking:

1. Move all Tidier packages to DocumenterVitepress.jl
2. Keep some high-level tutorials on the Tidier.jl website, with a focus on examples that rely on functionality across the packages
3. Detailed examples for base packages will sit on the package-specific docs (e.g., for TidierData, TidierPlots, etc).

This sounds like a great way forward to me. Tidier.jl docs can act like a sort of integration test to make sure all the packages work well together. Ideally we can start adding doctests to the documentation to really enforce no breaking changes (or at least that breaks are caught).

[camilogarciabotero]

I agree, I believe DocumenterVitepress.jl will benefit the scope and appeal of the Julia ecosystem. It needs some time though to be the default.

Are there any examples of Julia package ecosystems that already do this?

I was planning to open this conversation by turning all packages to DocumenterVitepress.jl, yet it needs a good effort. Kudos you are willing to pursue the transition. My thoughts on how to start this is to follow the "template" of the Chairmarks.jl docs. Where they don't have a home landing page. This in fact will be more similar to current Documenter.jl filesystem and configuration, because there is no need for the .vitepress template files.

So here's my thinking:

1. Move all Tidier packages to DocumenterVitepress.jl
2. Keep some high-level tutorials on the Tidier.jl website, with a focus on examples that rely on functionality across the packages
3. Detailed examples for base packages will sit on the package-specific docs (e.g., for TidierData, TidierPlots, etc).

I agree with this strategy.

Can an issue be opened on the Tidier.jl repo listing all the packages that need updating do DocumenterVitepress.jl?

Go on, if we follow the simple, no-landing page, I guess it could be addressed!

[camilogarciabotero]

I believe the conversation turned into something different from the original issue, which I think could be a starting point to improve not only the appearance of TidierPlots.jl but also its documentation content.