Meta: suggestions for documentation improvements

[odow]

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: jump-dev/JuMP.jl#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 High level documentation structure #1234
• Organize the docs using diataxis Reorganize the Manual > Syntax page #2246
• Document how to number and reference equations Equation numbering #975
• Document the Revise.jl watch'n'build workflow Document the Revise watch'n'build workflow #828
• Document how to reference
  • a specific method in @docs docs Block Methods #569
  • a method with optional arguments @docs for optional positional and keyword arguments; args..., kwargs... #2037
• Document how to reference the bare method function f end and specific ones Docstring for empty function prevents method docstrings from appearing #1390
• Remove the examples, or link to a few high quality docs Examples should be updated #1660
• Explain how @ref works for functions from other submodules Add context on current module for @ref link's #1714
• Document how to set parameters in Documenter.HTML How to set HTML parameters (e.g. disable_git, edit_link)? #2017
• Generally revise the makedocs docstring Revise the makedocs docstring #2079
• Fix suggestions to use PkgDev. [docs] PkgDev.generate doesn't exist #2119
• Document how to use Documenter with package extensions Issues with package extensions #2124
• Add a troubleshooting guide Formulate a FAQ/troubleshooting page in the docs #2138
• Add a tutorial for using literate Literate.jl getting started example #2200
• Explain how to modify IOContext Document how to modify IOContext parameters in outputs #2207
• Document the remotes keyword Documentation improvements for remotes keyword #2242

Deployment

• Add docs on how to setup and generate the docs locally Document how to generate docs locally #1413
• Add docs on how to deploy the PDF PDF Deployment Instructions #1218
• Document that packages should be added with Pkg.dev in CI so that their source links work (Missing docstring source links #834)
• Document what is needed to use tectonic` makedocs using tectonic fails because of missing DevaVu font #1817
• Document how to use typos or vale Feature Request: Spell check #2122
• Simplify Hosting Documentation to focus on GitHub actions Reorganize Hosting Documentation #2131
• Clarify setup of deployment keys Out-of-repo deployment doesn't work for me  #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) Document code parsing rule (at least 7 spaces in front of it). #1159
• Document the various rules around $ and the inline latex \[ \] and \( \) etc. Documenter.jl eats the inline math markup #377
• Document Julia types of function options/kwargs #2450

Internals

• Document the internal structure. What are all the nodes? What is an expander pipeline? Formalize the syntax that a writer is guaranteed to support #874

[evanfields]

Thanks for this meta-issue!
I'm trying to pull TravelingSalesmanHeuristics's docs out of the dark ages (apparently made 4 years ago and not updated meaningfully since) and finding it pretty confusing. A few things tripping me up so far:

1. Why is docs/Project.toml only relevant for hosting documentation, i.e. why does the "docs/Project.toml" section of the Documenter docs live in the hosting section? Won't I need a documentation environment for building locally?

2. What packages go in docs/Project.toml? The Documenter docs show just Documenter, but many well known packages in the ecosystem diverge. Example.jl follows this, though with a 3 year old version of Documenter so maybe I shouldn't trust it? JuMP puts lots of dependencies (what's a doc dependency?) as well as JuMP itself. DataFrames puts lots of dependencies but not DataFrames itself.

3. Github Actions workflow for documentation: the Documenter docs suggest a separate workflow file with particular structure, but seems like most ecosystem packages (Example.jl) use a different [shorter] job in their main ci.yml?

4. Authentication: the Documenter docs treat GITHUB_TOKEN and DOCUMENTER_KEY as either/or, but most packages in the wild include both in their workflow files, is this just a widespread mistake?

5. Setting up the Julia environment for building locally. I've always found stacked environments and Pkg.dev to be extremely confusing elements of Julia's otherwise sublime package manager, so maybe this is just a me problem. But, I'm not sure how to set up the environment for building docs locally. Following the Documenter guide I added push!(LOAD_PATH,"../src/") to the top of my make.jl, and tried to build with cd docs; julia --project make.jl but am getting an ERROR: LoadError: MissingRemoteError: unable to generate source url. Googling for this error finds a menagerie of Discourse threads and GitHub issues stretching back years where people suggest various snippets -- most of which seem to be dynamically adding the package to be documented to the docs environment -- but I'm not sure what the up-to-date recommendation is or where I went wrong trying to straightforwardly follow the Documenter guide. Edit: I seem to have proximally solved this issue by following the error advice and doing ]dev ./.. in the docs project. But now my docs/Project.toml doesn't match the Documenter docs recommendation and I'm unsure if I did the right thing. The suggested Remote Repository Links section of the documentation is pretty confusing but probably has some answers?

[mmikhasenko]

Some more on starting with the Documenter.

The first page of the guide suggests adding Documenter to direct dependencies of the file. I have not seen many people doing it. It is more common to have a separate Project.toml in a docs folder. It would be nice to document the workflow with dev of the main package.

I ended up having five lines of Pkg gymnastics at the header of my docs/make.jl file.

using Pkg
cd(joinpath(@__DIR__, ".."))
Pkg.activate("docs")
Pkg.develop(PackageSpec(path=pwd()))  # adds the package that is being documented
Pkg.instantiate()  # download & install dependences specific for the documentation

[goerz]

In the context of #2385 I was reading through some of the docstrings in a bit more detail, and there's quite a lot of information that is outdated or plain confusing.

Maybe we should create a docs-improvement branch where everyone with write permissions can just freely make changes to the docstrings or any other part of the documentation, including typos and such. Anything that doesn't involve changes in the actual code.

We could then review the changes on that branch in bulk during the monthly community call, merge it, and then start a new branch for the next month.

[mortenpi]

Maybe we should create a docs-improvement branch where everyone with write permissions can just freely make changes to the docstrings or any other part of the documentation, including typos and such.

PR-ing them one-by-one seems easier to me? Docs changes are generally relatively easy to decide on and merge, and smaller the PR is, the easier the review in my opinion.