GNOME developer website needs an update

Hi there!
First, thanks for all the hard work as well as GTK4! Can’t wait to start using it.

This is my first post on here. In fact I made an account to come and say this. The GTK developer website looks a bit dated and giving it a face-lift can bring new energy to the community, IMO.

But it’s not just a matter of redesigning it. Since the developer website documents guides and the API reference, and since the API reference documents many versions of GTK, I’d like to suggest using Read The Docs. It’s quite versatile, popular and is a modern tool. We can even style it to the community’s content (e.g. see Godot’s docs).

Thank you and happy holidays!

Hi, welcome to the community :slight_smile:
I think we would all agree about the state of developer.gnome.org.

There was an initiative to revamp it, which you can read about on @bastianilso’s blog: this post is a good starting point. I haven’t seen much progress recently, so I think nobody is volunteering any time on the initiative at the moment.

Would it be possible to move to readthedocs.org? GTK uses gtk-doc for documentation, and I believe readthedocs.org requires Sphinx or mkdocs. I think we’d likely also want a self-hosted solution rather than relying on a 3rd party. It would be great if there was a simple way to improve the developer.gnome.org site, though.

Happy holidays :slight_smile:

edit: I also found this on the wiki, which seems relevant.

It would be great if someone could, one day, go through the whole documentation part.

The documentation is not bad, but it is also far from perfect; ruby has a similar problem
by the way. Oddly enough, python has a very good documentation - I am reading a pygtk
book right now and the examples can almost be used 1:1 in ruby. :slight_smile: (One has to adjust
things a bit, but since I know both ruby and python, this is not difficult.)

I think if the official documentation could be improved, I’d try to make it a bit more like
a wiki, allowing user contributions too, and a bit of collecting snippets from, say,
stack-overflow. I’d also visually make the font size a bit larger and easier to read.

Python has some nice documentation as example.

I am also aware that nobody wants to write documentation really, I understand
that, but someone has to do it eventually. :stuck_out_tongue:

I think we’d likely also want a self-hosted solution rather than relying on a 3rd party.

This would be good; I think KDE has done something similar to this lately with the
re-design of their website and related parts. There tend to be two main user group
for documentation - the newcomers. They need all the help. And then, the more
experienced guys; they tend to need more quick references only. Right now it seems
gtk/gnome caters more to the more experienced guys, which makes it hard to get
entry into. The higher that initial barrier is, the less likely people go to it. (Qt has a
similar problem by the way.)

Are you aware of https://wiki.gnome.org/Newcomers ?

Valadoc is a lot better as an API doc. Even though it’s made for Vala, the classes are usually all built the same way in C because they use gobject.

We are not going to use ReadTheDocs for GNOME API references: we prefer hosting our documentation ourselves, since it’s supposed to be integrated with our release infrastructure.

Additionally, API references for C libraries are generated via gtk-doc.

Sadly, the developer.gnome.org website is managed by library-web, which is, by and large, unmaintained at the moment.

Any attempt at fixing library-web would need to:

  • integrate with gnome-build-meta which is the set of recipes and scripts we use to generate Flatpak run times, GNOME OS images, and GNOME releases
  • not require tarballs to contain documentation—which is something only Autotools does
  • deal with both API references and application documentation
  • deal with additional static sources, like the development guides, the “How Do I” wiki pages, etc.
  • deal with generating searchable indices of symbols

In practice, it’s a complicated task, and nobody has showed up to take it over.