search

LuxDL / DocumenterVitepress.jl

Documentation with Documenter.jl and VitePress
https://luxdl.github.io/DocumenterVitepress.jl/
MIT License
63 stars 9 forks source link

Add an option to serve stable documentation without a version number in URL. #73

Open LilithHafner opened 3 months ago

LilithHafner commented 3 months ago

I want to serve my stable docs from chairmarks.lilithhafner.com/tutorial rather than chairmarks.lilithhafner.com/v1.1.2/tutorial or whatever happens to be the latest stable version.

There are two problems here.

  1. No version specifier in the URL. Like Documenter.jl's approach of chairmarks.lilithhafner.com/stable/tutorial, and like the rest of the internet, this will result in broken links when I remove or rename pages without adding a redirect. However, this is the behavior I want. If someone tries to access a link to a part of the documentation, they should receive the corresponding page on the latest version or an error if none exists unless they actively seek an out of date version.

  2. Possible name conflicts. My docs do not include dev, previews, or v\d.* pages, so I'll be fine for now. I'd expect to get an error and failed documentation build (though not a corrupt gh-pages branch) if I try to add a page that conflicts or if DocumenterVitepress or Documenter adds a directory that conflicts with one of my pages. These plausible name conflicts seem like a maintainability footgun.

asinghvi17 commented 3 months ago

This sounds like an implicit promise to not change page structure across versions?

Also, I'm not entirely sure this can be done with Documenter as it stands...

LilithHafner commented 3 months ago

This sounds like an implicit promise to not change page structure across versions?

Across versions of Documenter/DocumenterVitepress or across versions of the package whose documentation is being built?

I'm assuming it would be the responsibility of the folks who are foolish enough to turn on this feature to handle name conflicts as they come up.

Also, I'm not entirely sure this can be done with Documenter as it stands...

I assumed we were already doing something similar here b.c. DocumenterVitepress redirects .../stable/... to .../vx.y.z/... while Documenter simply serves pages at .../stable/....

Anything is possible :P. My question is whether this is unsustainable enough that you don't want to enable package developers to opt into it.

asinghvi17 commented 3 months ago

I was thinking across versions of the package whose docs are being built.

I assumed we were already doing something similar here

We aren't - that's all in deploydocs, which does not dispatch on format unfortunately. I'm not sure whether a plugin is possible for that though?

@goerz would know more than I do about this

asinghvi17 commented 3 months ago

We could provide custom functions to the make kwarg in deploydocs: https://github.com/JuliaDocs/Documenter.jl/blob/a6f6c0c7e33f4b0c3fab38811ac691d646e2d46c/src/deploydocs.jl#L273-L276