search

gridcf / gct-docs

Grid Community Toolkit documentation
http://gridcf.org/gct-docs/
1 stars 4 forks source link

Versioned documentation #7

Closed fscheiner closed 5 years ago

fscheiner commented 5 years ago

This PR now changes the GCT documentation to versioned documentation:

Mockup

https://fscheiner.github.io/gct-docs/

Consequences

This PR also requires changes to the code resuts for this search as they link to non-exsiting URLs after this PR is applied.

Possible options/alternatives

fscheiner commented 5 years ago

Regarding URL rewriting/redirects, I now think that we cannot use the automatism provided by JekyllRedirectFrom, because we don't use MD files as basis from which jekyll would create HTML on-the-fly, but serve HTML pre-produced from ADOC. But we could use the same technology, i.e. provide static HTML files with included meta refresh for the relevant index documents. But still, this won't work for the main index document. In addition these redirects only make sense with a "static" target directory part, i.e. with the symlink solution, else we would have to update the redirects every time a new major/minor release of the GCT is made.

Alternatively I could provide a patch for the GCT to update the URLs, but this won't make it into packages before the next (maintenance) release.

matyasselmeci commented 5 years ago

I think the latest->6.2 symlink is fine. I think most of the time people would be interested in the latest documentation anyway.

msalle commented 5 years ago

I'm a bit confused, why can't you put in the index.adoc

In any case you will need to update it for the next release? And if someone needs to be referred to the always-latest documentation, they can go to https://gridcf.org/gct-docs/ itself? You can still create the symlink, that would probably be useful, as long as we make sure every page clearly states the actual version. That's more or less also what http://toolkit.globus.org/toolkit/docs/ did.

fscheiner commented 5 years ago

@msalle

I'm a bit confused, why can't you put in the index.adoc

link:./6.2/index.html[Latest stable]

In any case you will need to update it for the next release?

That's true, for any new point or major release the main index document still has to be updated. So we don't get around these updates when using a symlink. But the symlink will allow us to refer to a fixed URL for any documentation links, for example in the package descriptions of pre-compiled packages.

And if someone needs to be referred to the always-latest documentation, they can go to https://gridcf.org/gct-docs/ itself?

That would be one additional "hop" if users just want to check the latest docs.

You can still create the symlink, that would probably be useful, as long as we make sure every page clearly states the actual version. That's more or less also what http://toolkit.globus.org/toolkit/docs/ did.

I think that's the case for our docs.

@matyasselmeci @msalle So, ok to merge?

msalle commented 5 years ago

I'm a bit confused, why can't you put in the index.adoc link:./6.2/index.html[Latest stable] In any case you will need to update it for the next release?

That's true, for any new point or major release the main index document still has to be updated. So we don't get around these updates when using a symlink. But the symlink will allow us to refer to a fixed URL for any documentation links, for example in the package descriptions of pre-compiled packages.

I see your point with specific links. It's probably indeed not really doable to do better at this stage.