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

[Rob Clark]

On Fri, Jun 21, 2019 at 7:01 AM Erik Faye-Lund
<erik.faye-lund at collabora.com> wrote:
>
> 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/

I don't have too much intelligent to add, but:

* I'm glad someone is picking this up again
* split of docs.mesa3d.org seems fine if it simplifies things logistically
* new front page looks nice and I'm glad it kept this spinning gears
easter egg :-)

BR,
-R

>
> 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?
>
>
>
> _______________________________________________
> mesa-dev mailing list
> mesa-dev at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/mesa-dev