[Roadmap] Documentation

[SimonDanisch]

Documentation Rewrite project

REPL first, make docstrings source of truth

Every piece of documentation should be accessible from the REPL/VScode/Jupyter, ideally with example plots being shown interactively.
So ?Axis.xscale should pop up documentation of the xscale attribute with examples of how to use it. Ideally this should work for an axis instance, e.g. ?axis.xscale as well, but then with examples showing how to mutate it.

This requires certain infrastructure changes:

• write more docstrings with better examples, make sure most things are documented
• We may need the ability to add more information to the documentation system (e.g. for interactive examples, or to make it easier to create our web documentation from it), so this could create the need to use our own documentation system. If this is the case, we should make sure it still hooks up with the julia standard documentation system, just with less fancy features.
• Documentation should be more modular for context-specific access.
• Better incorporate examples within the documentation system.
• Rewrite the current Franklin docs to auto-generate from docstrings, creating a systematic, searchable representation of our documentation. We likely will need to drop Franklin for this and switch to JSServe.
• Reference image test docs

Desired Documentation Improvements for the website

• Improved search functionality.
• Enhanced navigation and accessibility (e.g. easier access to FAQ, improved menu structure).
• Consistent design with uniform font size and spacing.
• Increased number of tutorials.

Discussions about improving the docs:

• Restructuring the docs #2887
• Makie docs with Pollen and Docusaurus #2284
• Introduction to Makie and conceptual basis #2854
• Time for a new Documentation template and re-structure? #3222

Missing content (or functionality):

• Missing docstring for Figure #3118
• [Docs] Ideas for additions to docs #307
• Sitemap #1519
• Improve docs for displaying figures in CairoMakie #2897
• Improve docstrings for Blocks #2928

[ffreyer]

Some questions/comments for docstrings:

• Should output types be noted in the call syntax? Most currently don't, but a few note them as f(...)::Type or f(...) -> Type.
• We should have some kind of standard/template to follow to keep docstrings consistent. Maybe we could add a section on contributing in the docs which includes this
• What should get docstrings and how complex should they be? I would say
  • Functionality meant for end users (like scatter, Axis) should as exhaustive as it gets
  • Functionality meant for third party developers/packages should contain a similar amount of information but not be as strict. For example, we shouldn't document every convert_arguments method or list every possible conversion. Rather we should explain how it works, how to extend it and what conversion targets (for plots and traits) exist.
  • Complex functionality meant for Makie devs, things like layout_text should be briefly documented. Usually no example, a short description of what it does, what the inputs are (if not obvious) and what assumptions/potential pitfalls exist if there are any.
  • Internal functions that are very specific/localized, or self-explanatory don't need to be documented. Something like marker_to_sdf_shape or show_data_recursion can just have a comment.
• I think length of docstrings is also important to consider. With ?Camera3D or ?scatter you currently get a wall of attribute docs so you're pretty much forced to scroll up if you want to read the description or see the call syntax. ?Axis on the other hand defers the attribute docs so you can see the description and call syntax much more easily. I personally prefer this.

[tecosaur]

For having a short description + elaboration in a docstring, I'd just like to add that I think # Extended help is currently underutilized.