Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Meta: suggestions for documentation improvements #2321

Open
28 tasks
odow opened this issue Nov 1, 2023 · 4 comments
Open
28 tasks

Meta: suggestions for documentation improvements #2321

odow opened this issue Nov 1, 2023 · 4 comments

Comments

@odow
Copy link
Collaborator

odow commented Nov 1, 2023

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

Deployment

Niggles, gotchas, and things to be aware of

Internals

@evanfields
Copy link

evanfields commented Nov 10, 2023

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
Copy link

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
Copy link
Member

goerz commented Jan 29, 2024

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
Copy link
Member

mortenpi commented Feb 3, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

5 participants