Follow

After fighting against library-web for a couple of months, I ended up switching to Sphinx for the new developer.gnome.org website—following the work done by the design team for the new HIG. Turns out it was a very good choice, because now we have a decent developer documentation website that we can easily improve, instead of an opaque Django monstrosity that we can't even test locally.

· · Web · 2 · 2 · 5

The remaining task is publishing the API references for the libraries in the SDK—which we're already building for the org.gnome.Sdk.Docs run time extension: gitlab.gnome.org/GNOME/gnome-b

Separately, I'm looking into being able to install and browse locally the documentation of different versions of the SDK using Devhelp: gitlab.gnome.org/GNOME/devhelp

Additionally, I'm working on a CI template for libraries hosted on gitlab.gnome.org, to allow them to build and publish their API reference as part of their CI pipeline.

Once all of that is done, maybe I'll try to work on world peace. It'll likely be easier.

@ebassi What about achieving peace between Linux communities? xd

Jokes aside, excellent work, as always :)

@ebassi The main problem I see with the new site is that all existing links to documentation have broken. I just tried to open developer.gnome.org/glib/unsta to look up some info (have that link in my browser history), and … 404. I can't even find the glib docs from the top page of the site?

@kepstin literally put in the announcement on Discourse where the old docs are, and that we’re working on a new set or API references; kind of tired of repeating myself everywhere, to be honest…

@ebassi Well… given that I started from a generic gitlab 404 page when trying to access docs, and only find out from social media later what happened, it's pretty frustrating.

Was there no way you could keep the docs at the same URLs? If they've moved, it would be appropriate to put redirects in place. The absolute bare minimum would be to have a non-generic 404 page that points to where the docs live now :/

@kepstin If we had the ability to keep the old URLs we would have. The problem with the old website was that the entire structure was managed by a single Django app written 15 years ago, and the structure itself was one of the pain points.

The URLs will change. That is unavoidable. The old docs at developer-old.gnome.org are the transition towards new API references.

Additionally, the GLib documentation will be moved to docs.gtk.org, as soon as I finish rebuilding it.

@ebassi If the URLs change, fine. I have no issue with that. Just put in redirects! Please help keep documentation links in forum posts and stackoverflow posts and irc logs working, or at least do your best to help people who come from those links find out where the appropriate documentation lives now.

@kepstin The redirects are complicated, and we might be able to set *some* of them up on Monday.

Please, don't assume people are entirely incompetent.

@ebassi To try to do something a bit more constructive, I've made an MR to add a link to the old docs site from the new one: gitlab.gnome.org/Teams/documen

The biggest pain point I had was simply that I couldn't find any way to get to the docs I wanted to read from developer.gnome.org/ - I only realized that the developer-old site existed later when I was pointed to the forum post about the change.

Sign in to participate in the conversation
Mastodon

Server run by the main developers of the project 🐘 It is not focused on any particular niche interest - everyone is welcome as long as you follow our code of conduct!