Standard `makedocs` call fails if you aren't in a git repo

[asinghvi17]

┌ Warning: Unable to determine HTML(edit_link = ...) from remote HEAD branch, defaulting to "master".
│ Calling `git remote` failed with an exception. Set JULIA_DEBUG=Documenter to see the error.
│ Unless this is due to a configuration error, the relevant variable should be set explicitly.
└ @ Documenter ~/.julia/packages/Documenter/ZlqFj/src/utilities/utilities.jl:660
ERROR: LoadError: ArgumentError: Unable to automatically determine remote for main repo.
> `repo` is not set, and makedocs is not in a Git repository.
Configure `repo` and/or `remotes` appropriately, or set `remotes = nothing` to disable remote source
links altogether (e.g. if not working in a Git repository).
  repo: nothing
Stacktrace:
 [1] interpret_repo_and_remotes(; root::String, repo::String, remotes::Dict{Any, Any})
   @ Documenter ~/.julia/packages/Documenter/ZlqFj/src/documents.jl:667
 [2] interpret_repo_and_remotes
   @ ~/.julia/packages/Documenter/ZlqFj/src/documents.jl:504 [inlined]
 [3] Documenter.Document(; root::String, source::String, build::String, workdir::Symbol, format::Documenter.HTMLWriter.HTML, clean::Bool, doctest::Bool, linkcheck::Bool, linkcheck_ignore::Vector{…}, linkcheck_timeout::Int64, linkcheck_useragent::String, checkdocs::Symbol, checkdocs_ignored_modules::Vector{…}, doctestfilters::Vector{…}, warnonly::Vector{…}, modules::Vector{…}, pages::Vector{…}, pagesonly::Bool, expandfirst::Vector{…}, plugins::Vector{…}, repo::String, remotes::Dict{…}, sitename::String, authors::String, version::String, highlightsig::Bool, draft::Bool, others::@Kwargs{})
   @ Documenter ~/.julia/packages/Documenter/ZlqFj/src/documents.jl:432
 [4] makedocs(; debug::Bool, format::Documenter.HTMLWriter.HTML, kwargs::@Kwargs{…})
   @ Documenter ~/.julia/packages/Documenter/ZlqFj/src/makedocs.jl:267

We should make this simply default to what happens when remotes = nothing.

[asinghvi17]

It seems to me that the first branch of this should not error.

Documenter.jl/src/documents.jl

Lines 653 to 668 in ced42e5

	else
	# Finally, if we're neither in a git repo, and nothing is in remotes,
	err = "Unable to automatically determine remote for main repo."
	err *= '\n'
	err *= if isnothing(repo_normalized)
	"""> `repo` is not set, and makedocs is not in a Git repository.
	Configure `repo` and/or `remotes` appropriately, or set `remotes = nothing` to disable remote source
	links altogether (e.g. if not working in a Git repository)."""
	else
	"""> `repo` is set but makedocs is not in a Git repository. You should configure `remotes` instead,
	with the appropriate local path pointing to the repository root."""
	end
	err *= '\n'
	err *= " repo: $(repo_normalized)"
	throw(ArgumentError(err))
	end

[fingolfin]

I'd say this works as intended. Specifically, the error message says this:

Configure repo and/or remotes appropriately, or set remotes = nothing to disable remote source
links altogether (e.g. if not working in a Git repository).

[asinghvi17]

Why should this error, is more the question to me. A warning seems sufficient?

[fingolfin]

How did you invoke makedocs exactly?

[asinghvi17]

Just from a file? But not in a git repo. This was specifically to create and display documentation locally.

[goerz]

I'd say this works as intended.

I haven't looked at the details of how all of this fits together, but I would say we should have the goal to make it easy to locally build the documentation of a package that is not (yet) a git repo. It's okay to show warnings, but the build should work, IMO.

[mortenpi]

Why should this error, is more the question to me. A warning seems sufficient?

In particular on CI, people don't see warnings. If we don't error, people will not notice if they somehow manage to break the automatic repo detection (like, you change some CI setting and suddenly it's not a proper Git repo anymore or something, because it's pulling down a release tarball -- approximately real case from Julia's own docs / BuildKite), and then they happily deploy docs for e.g. tags that don't have proper source or edit links. This was a pretty common issue pre-1.0, where the remote link handling was more tolerant.

The non-Git use case is valid, but relatively unusual in my opinion. So it's better to require the user to set repo/remotes in that case. Another alternative would be to remove the automatic detection altogether and require users to set repo manually (but I think the automatic system is useful, and changing it this way would be kinda breaking anyway).

What I think we should do here is to have better docs for this, and maybe also expand on that error/warning message.

[asinghvi17]

Can we at least have the error occur only in CI, then?

[goerz]

I could see turning some warnings into errors depending on the presence of the CI environment variable, although that’s not mutually exclusive with better docs or error messages.

[mortenpi]

Can we at least have the error occur only in CI, then?

No, sorry, I'm pretty strongly against this. We've been trying to move away from this type of implicit behavior. I don't want to bring it back.

Making things depend in CI will create a lot of confusion of the type "It works locally, but breaks / works differently on CI.", which is hard to debug (in particular for a beginner or average user). It also conflates errors that are due to a different environment with ones that are due to Documenter behaving differently in a different environment, again making things harder to debug. The remote link stuff in particular was such a pain for users pre-1.0 (although most users didn't realize they were deploying broken docs).

Documenter is predominantly meant and used for documenting package code. On the balance of things, asking users to set one more option to repo doesn't seem particularly bad? In my opinion, many more users will be affected by the negative consequences of this change, rather than the positive.

---

Also, tangential thought: we shouldn't think of Documenter being restricted to one single purpose. E.g. another case where you need to decide how Documenter works is deploying versioned docs vs a single-page (like a org landing page). Generally, I feel that we really want to support different "modes" that behave slightly differently. But the makedocs interface we have right now kinda forces us to choose a default mode. Which right now is aimed for CI-deployed Julia packages.

[asinghvi17]

From discussion we settled on having something like repo = Documenter.OptionalRepo() that will trigger ignoring this behaviour if not in a repo. Closing this in favour of that kind of solution.

If anyone has suggestions for the name that are better please chime in :D

Yeah, there are usecases I'm aware of for DocumenterMarkdown to build for random Markdown based web tools (retype, sli.dev, etc) which would be really nice to support, then Documenter becomes more general purpose as well.

[mortenpi]

Just for future reference: the motivating use case is basically auto-generated package-like code that also has a documentation build attached. That code doesn't always live in a Git repo, but sometimes may be moved into one later. But you don't want to force users to edit the generate code by hand when that happens, so deciding things dynamically is good in this case. (I think I got that mostly right @asinghvi17?)

But we can have the code generator output the necessary repo = .. value, rather than having to change Documenter defaults.