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