On Fri, Jun 21, 2019 at 7:01 AM Erik Faye-Lund <[email protected]> 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 > [email protected] > https://lists.freedesktop.org/mailman/listinfo/mesa-dev _______________________________________________ mesa-dev mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/mesa-dev
