Skip to content

docs: sphinx-conversion

Erik Faye-Lund requested to merge kusma/mesa:docs-sphinx-conversion into master

OK, so here's a long-time coming one, and it's a bit tricky to untangle.

For a while now, I've been playing around with a revamp of the Mesa website, rooted in frustration with the maintenance burden of our current website, all stemming from maintaining this as explicitly written HTML:

  • HTML markup is hard to write by hand. We often make mistakes that aren't caught until late.
  • Any change to the HTML boilerplate is very painful at the moment:
    • Our website is currently stuck at HTML 4.01, while HTML5 has been around for a while and is widely adopted
    • Any modernization of the website design is similarly not very attractive.
    • The website renders horribly on mobile (understandable, because mobile websites wasn't a think back when it was designed), and this is often bothering me when trying to read up on something when I'm not in front of a computer.
  • As a side-note, HTML markup is hard to read without a web-browser. There's better markup formats for more human-readable documentation out there.

So here's an attempt at fixing that. This is based on previous work by @ldeks (and I believe others).

So, what I'm doing here, is to convert the documentation to Sphinx using Pandoc and bunch of Python glue-code. The documentation gets compiled into HTML using GitLab CI, and is hosted on GitLab pages. We could also consider hosting it at Read the Docs in the future if we want the extra bells and whistles they provide.

You can see the result in action here.

The reason why this is marked as WIP, is that I don't quite want to stop there, as the last commit in this series hints to. I've also created a proof-of-concept of what I consider to be a bit more of a proper website. The idea to split the current website into a website and a documentation site:

  • The website is more "marketing" oriented
    • Explains a bit about what mesa is
    • Where to get the source code
    • Contains news about the project
      • Additionally served as an RSS / Atom feed
    • ...but mostly links to the documentation site for the details
  • The documentation site is more information oriented
    • Contains the same technical documentation as comes with mesa
    • Can remove information better explained at the website
      • About, Downloads, News etc
      • There's probably a lot more discussions to be had about what belongs where

You can see the website prototype in action here.

Some notable improvements over the status quo (some repeated from before):

  • No need to maintain hand-written HTML
  • Modern, mobile-friendly designs for everything
  • Marketing material separated from technical material
  • Using modern tools, specialized for each purpose
    • Sphinx for the docs, Jekyll for the website (for now)
  • The gears now rotate when hovered ;)

I also talked a bit about this in a BoF at FOSDEM 20, in case anyone is interested.

Edited by Daniel Stone

Merge request reports