Add stable version of docs?

[cdeil]

Currently we only have http://docs.gammapy.org/stable/ which forwards to the latest stable version, but other pages like e.g. http://docs.gammapy.org/stable/maps/index.html don't exist.

I think most software docs offer URLs for "stable", e.g. on RTD this is the default behaviour that you get, to give an example: http://docs.astropy.org/en/stable/time/index.html

But not all projects do this, e.g. with Flask you get a 404 just like currently with Gammapy:
http://flask.pocoo.org/docs/stable/quickstart/

I'm +1 to offer all the pages under "stable", but not strongly. I think often it is useful to share a link like http://docs.gammapy.org/stable/maps instead of e.g. http://docs.gammapy.org/0.7/maps , but obviously this practice also has the drawback that some links will break especially Gammapy pre-1.0 as we refactor code and docs.

@Bultako or anyone interested - Thoughts

Technically putting the docs under "stable" isn't hard; we just have to commit a copy of the files under https://github.com/gammapy/gammapy-docs/tree/master/docs/stable/ and update it as new versions are released - a step on a release check-list or even automated somehow.

[Bultako]

I would not offer a /stable URL-path version of the docs.

The main reason is that the content represented by those /stable links will evolve with time very soon (content changing does not seem very stable) I guess Gammapy is not still in a logic of releasing LTS stable versions of the software.

We are providing versioned 0.x/ URLs pointing to fixed snapshots of the docs, and a dev/ URL pointing to work in progress content. This behavior seems sensible to me.

I would prefer instead to have a http://docs.gammapy.org/latest/ pointing to dev/ if I you ask me what changes we should do in the URLs of the docs, though it's only a suggestion, not a strong opinion on this.

[cdeil]

We did have "latest" when we were on RTD. I changed to "dev" because I thought "latest" is confusing, it's unclear if it's "latest development version" or "latest stable version", so I found "dev" to be clearer. OK to stick with "dev"?

I agree with the argument that "stable" isn't great because it won't be stable, so OK not to add it.

How about we add a custom 404 page to help users a bit if they land on a page that doesn't exist?
https://help.github.com/articles/creating-a-custom-404-page-for-your-github-pages-site/
Not sure yet what it should say exactly and where to point. I'll make a PR for the 404 page and then we can discuss there.

[Bultako]

OK to stick with "dev"?

👍

I'll make a PR for the 404 page and then we can discuss there.

👍

[cdeil]

404 page for gammapy.org: gammapy/gammapy-webpage@94aaaab

[cdeil]

404 page for docs.gammapy.org: gammapy/gammapy-docs@cbeeb9c

[cdeil]

To review the current 404 pages, you can follow these links:

• http://gammapy.org/spam
• http://docs.gammapy.org/spam

At first I started to explain the docs version scheme in more detail and also mention the dev docs. But in the end, I think most users don't care and prefer just a short message.

@Bultako - Please review.

[Bultako]

Good ! 👍

Some comments for http://docs.gammapy.org/spam

• Could we add a simple banner on top? Just to really make clear from the first glimpse (for lost users) that this is not a blank page provided by the browser or coming from other internet/connection issues? See screenshot below.
• I would remove "Use the search field or navigation sidebar on the left to browse a given version." There is no navigation sidebar or search field in the 404 page. I think it may lead to confusion, let's make thinks simple and clear for this page.
• I would relocate the link in the sentence "Links to older versions of the Gammapy documentation are here", so robots that index content can put the good context to the link. For example, if we say instead "Access older versions of the Gammapy documentation" we can be more confident that web search engines will deliver a good answer when people will search for "older versions of gammapy documentation". In general, texts in links should be descriptive enough of the content they refer to (let's avoid links like here or click here)

[cdeil]

@Bultako - Done in gammapy/gammapy-docs@73a626d .