[Mesa-dev] Proposal for the future of www.mesa3d.org

[Erik Faye-Lund]

A while back, Laura and Jean was working on a Sphinx-conversion of the
mesa-documentation. Sadly this work stranded due to it also trying to
move to using GitLab Pages for hosting www.mesa3d.org, and because the
documentation and the websit eis the same thing, this lead to problems
with hosting the release-archive (www.mesa3d.org/archive/).

Since then, I've taken a look at trying to revive this work. So far,
I've taken most of the changed Laura did to the website post-RST
conversion, and performed them before instead. I've also automated more
of the conversion process, so we can easier get an up-to-date
conversion. The result can be viewed here:

https://kusma.pages.freedesktop.org/mesa/
https://gitlab.freedesktop.org/kusma/mesa/tree/docs-sphinx-v2

Please note that there's some differences:
- I don't do any "mesa-specific styling". This can be done on top if
needed, simply by cherry-picking Laura's commits for this. But I'm not
sure we need it, more about this further down.
- Some of the commit history might be incorrectly attributed to me
instead of Laura. I intend to fix this up before upstreaming anything
here.
- The conversion isn't entirely up-to-date, but it's *fairly* recent.

So yeah, the big elephant in the room is what to do with 
www.mesa3d.org/archive. This is where I have an alternative suggestion:

How about we split the documentation and the website into two sites, 
www.mesa3d.org and docs.mesa3d.org, and maintain the website in a
separate repository? We would of course have to set up some redirects
to make old URLs point to the latest version (at least for a transition
period).

This has some additional benefits:
- We don't need to push things to master to update things like news,
that aren't really related to the code.
- We can separate information that is technical documentation from
information that are is "project marketing".
- ...And because we don't need for the docs to appeal as "project
marketing", we can keep the neutral readthedocs theme as-is, as it's a
bit more easy on the eye IMO.
- It makes the article index a bit more logical, as there's a few
articles that doesn't really make sense to read after you already have
the source tree. Why would you wonder who the webmaster is
(docs/webmaster.html) or where to download mesa (docs/download.html)
when reading the source?
- We can host docs.mesa3d.org using GitLab pages (or point it to
something like readthedocs.org) without having to change the hosting
for www.mesa3d.org.

In addition to this, I've also had a look at modernizing www.mesa.org 
as well, and I've made a proposal for a new, responisive website:

https://kusma.pages.freedesktop.org/
https://gitlab.freedesktop.org/kusma/kusma.pages.freedesktop.org/

Quite a few things to notice:
- Many links here forward to docs.mesa3d.org, which doesn't exist yet.
- The redirects are done using meta-refresh tags instead of HTTP
redirects, so they will only be redirected by an actual user-agent, not
by curl or wget.
- The site is using logos of Khronos APIs which might not be OK without
approval. The legality of this needs to be researched.
- Most of the content here is "usable placeholder" text, but by no
means final. For instance, the descriptions of the APIs and drivers
probably needs work. Especially the driver-decription should probably
be written by the driver-teams rather than me.
- Some drivers are missing. I just didn't bother writing more
placeholder.
- What content goes in which site is by no means decided on.
- Some content isn't yet in either site; in particular, non-html files,
like for instance the contents of www.mesa3d.org/specs. And since
GitLab pages doesn't do directory listings, that folder (regardless of
where it'd be reciding) would need an index added.
- The site is made using Jekyll, but any static-site generator would
do, really.

The redirect-issue is due to the prototype currently being hosted in
GitLab pages, and is a GitLab pages limitation. See 
https://gitlab.com/gitlab-org/gitlab-pages/issues/24 for more details.
I doubt this would be a problem for documentation, but the same
approach won't work for www.mesa3d.org/archive. Without solving that
problem, we can't really go live with this while hosting it on GitLab
pages.

But we could go forward *without* hosting www.mesa3d.org in GitLab
pages in the short term. I don't know how we currently deploy the
website, I guess that's done manually by someone at some points? If so,
we'd just update the manual recipie, I guess.

I think the long-term goal should be to also move www.mesa3d.org to
GitLab pages as well, and I have some ideas for how to deal with the 
www.mesa3d.org/archive-problem, but this is a much longer discussion,
and this email is already too long. So if someone wants to discuss
that, feel free to reply, and I'll happily tell you about it!

Anyway, thoughts? Objections?