juliadocs / documentationgeneratorregistry Goto Github PK

Current design:

[packages]
e5e0dc1b-0480-54bc-9374-aad01c23163d = { name = "Juno", method = "hosted", location = "https://docs.junolab.org/latest" }

I feel like I've become a nearly full time TOML file format designer, but here goes. The [packages] header seems unnecessary. It exists in the registry Registry.toml file because there's a bit of other metadata you need to know about a registry (originally they were in separate files, but I decided to put the package map in the same file as the registry metadata). I also think the stanza structure could be a bit different. Here are some sketches.

Here's a version using the UUID as a unique key:

[e5e0dc1b-0480-54bc-9374-aad01c23163d]
name = "Juno" # do we need this? I guess it's good to know in any case
method = "hosted"
location = "https://docs.junolab.org/latest"

[fcda24af-3677-4fa2-84a6-1f1efb146dee]
name = "SomePackage"
method = "git-repo"
location = "https://github.com/SomeOrg/SomePackage.jl.git"

If we want to support registering multiple hosting methods (do we?) then we could allow an array of stanzas per UUID, e.g.:

[[e5e0dc1b-0480-54bc-9374-aad01c23163d]]
name = "Juno"
method = "hosted"
location = "https://docs.junolab.org/latest"

[[e5e0dc1b-0480-54bc-9374-aad01c23163d]]
name = "Juno"
method = "git-repo"
location = "https://github.com/JunoLab/Juno.jl.git"

If we're going to allow multiple entries, it might be more readable to use the name as the key like we do in manifest files, e.g.:

[[Juno]]
uuid = "e5e0dc1b-0480-54bc-9374-aad01c23163d"
method = "hosted"
location = "https://docs.junolab.org/latest"

[[Juno]]
uuid = "e5e0dc1b-0480-54bc-9374-aad01c23163d"
method = "git-repo"
location = "https://github.com/JunoLab/Juno.jl.git"

[[SomePackage]]
uuid = "cda24af-3677-4fa2-84a6-1f1efb146dee"
method = "git-repo"
location = "https://github.com/SomeOrg/SomePackage.jl.git"

I registered a couple of packages here, but the process feels kind of arcane compared to JuliaRegistrator and Documenter deployment services, and probably quite alien to many less experienced package authors. Also it needs manual intervention, so it is hard to imagine how this could scale.

Isn't it just possible to look by default into the state of the gh_pages branch of a package repo in order to see if there is documentation which can be linked ?

See also the PR discussion at JuliaDocs/Documenter.jl#2548 and this zulip thread.