Meta: suggestions for documentation improvements

For a package all about documentation, the documentation of Documenter could do with some work. Rather than having a bunch of scattered issues, this meta-issue is a collation of ideas for things that we could improve.

• If you have suggestions for things to add or change, leave a comment below.
• If you're looking to contribute to Documenter, picking something off this list is a great place to start!

To focus efforts, we may close some of the linked issues (I've done this in JuMP, and it helped us focus efforts: https://github.com/jump-dev/JuMP.jl/issues/2348), but they will only be fixed if the box is checked.

As a high-level comment, there is a lot of content, but it could be better organized. We're also lacking some clearly written tutorials like

• How to setup Documenter for a new project
• How to edit the documentation of a package using Documenter
• How to deploy the PDF build to a website

as well as some manual-type deep dives on the peculiarities of syntax like @ref and @docs.

Things to help other people writing documentation

• Mention https://diataxis.fr #1234
• Organize the docs using diataxis #2246
• Document how to number and reference equations #975
• Document the Revise.jl watch'n'build workflow #828
• Document how to reference
  • a specific method in @docs #569
  • a method with optional arguments #2037
• Document how to reference the bare method function f end and specific ones #1390
• Remove the examples, or link to a few high quality docs #1660
• Explain how @ref works for functions from other submodules #1714
• Document how to set parameters in Documenter.HTML #2017
• Generally revise the makedocs docstring #2079
• Fix suggestions to use PkgDev. #2119
• Document how to use Documenter with package extensions #2124
• Add a troubleshooting guide #2138
• Add a tutorial for using literate #2200
• Explain how to modify IOContext #2207
• Document the remotes keyword #2242

Deployment

• Add docs on how to setup and generate the docs locally #1413
• Add docs on how to deploy the PDF #1218
• Document that packages should be added with Pkg.dev in CI so that their source links work (#834)
• Document what is needed to use tectonic` #1817
• Document how to use typos or vale #2122
• Simplify Hosting Documentation to focus on GitHub actions #2131
• Clarify setup of deployment keys #2403

Niggles, gotchas, and things to be aware of

• Document that code with the julia> prompt needs at least 7 spaces in front of it (i.e., as it would appear in the REPL) #1159
• Document the various rules around $ and the inline latex \[ \] and \( \) etc. #377
• https://github.com/JuliaDocs/Documenter.jl/issues/2450

Internals

• Document the internal structure. What are all the nodes? What is an expander pipeline? #874