New GNOME developer documentation website

Hi all;

the GNOME developer documentation website has been updated, after many years of service:

What changed

Instead of a custom web application, the new website is generated by Sphinx from simple reStructureText files, and automatically published through GitLab’s CI pipeline.

The content has been updated to reflect the current SDK and best practices, and it’s now easier than ever to contribute new guides and tutorials, as well as fixing the existing ones.

The Human Interface Guidelines have also adopted the same documentation platform:

API references

The API references will be published separately by the same GNOME build that generates run times and VM images; more information on that will be available soon.

Older content

The old developer documentation website has been transitionally moved to https://developer-old.gnome.org, so it’s not gone away for good.

20 Likes

Great work Emmanuele and all other contributors!

1 Like

Will a redirect be set up for all the old documentation links? Like https://developer.gnome.org/glib/stable/

Ideally, yes. In practice, the redirects will likely be used when we publish the SDK documentation.

Now most of the existing API docs links fail!

This is for links in tutorials, private bookmarks, and google provided links.

As DevHelp does not provide GTK4 Docs, I used in the last 18 months mostly my bookmarks or I asked google, i.e. with a query string like “gtk4 gtkentry” to get fast access to GtkEntry GTK4 API docs. This gives now a non existing page

https://developer.gnome.org/gtk4/stable/GtkEntry.html

3 Likes

I have the same problem. All the reference documentation is gone.

It’s not gone: the first post tells you exactly where it was moved.

It’s not gone: the first post tells you exactly where it was moved.

How long will it take google to update all its links?

How long will it take me to update all my browser links and the references in the GTK4 Nim book?

I think I have never seen such a drastic change in the last 20 years, not even for projects in an early alpha v.001 version state with only a few dozen of users.

You’re not meant to modify your links to go to the old website: it should be “fixed” in a few weeks (hopefully earlier) when the new site has most documentation.

1 Like

I understand the pain, but the site cannot be restructured in a way that is not going to break the existing URLs—short of literally creating a separate site. Then we’d have two different API references websites, one of which is not going to be touched any more, and will break Google and external websites, and confuse everyone looking for documentation.

The API references will be back, in a different tree structure that reflects the GNOME SDK, and attempt at fixing the issues raised in the past 10 years. Wherever possible we will attempt the creation of redirects, but not everything is possible.

4 Likes

Well, all the google searches still return the “old” links, which result in 404 errors.
So at least a “please look over there” wildcard page for the old content, would be helpful.

As I already said, we’re going to set up redirections wherever possible.

It’s way more difficult / less intuitive for me :frowning: I’m feeling dumb.
I never would think that the API would in “an overview” of “platform components”.
Captura de tela de 2021-08-01 13-22-45

Anyway, I couldn’t find the gtkmm docs (API and tutorials), and we have students in the middle of GSOC :confused:

Even these forums are hidden in the GTK website, at bottom, its “Community” page points only to Gitlab issues and Development blog. Same for GNOME page: the “Get Involved” does not provide info/links to forums or IRC channel.

Literally in the first post:

They are on developer-old.gnome.org: Developers - GNOME Developer Center

Sadly, the C++ bindings community is fairly insular and it’s hard to reach for real time conversations.

1 Like

Yes, it’s faded in the first post of this hidden forum :slight_smile: But thank you for pointing it. ( I edited my previous post while you answered me)
Maybe you could suggest the link to old docs in 404 page?

It seems that GitLab pages doesn’t support rewrite rules and only supports simple redirects, which indeed seems to rule out plain redirection to old docs straight from GitLab. However, wouldn’t it be possible to point the developer.gnome.org domain to a proxy webserver? It would just serve files from either the current GitLab site or from the developer-old.gnome.org site depending on the request path.

This might work for Apache:

It’s a Apache site config that proxies through the current website, except for subdirectories that were linked from the old main page as “doc-link”. These are redirected to the old website via HTTP 302 temporary redirect. The config works for me as-is on localhost but is unlikely to work in the final deployment – the GitLab site needs to be reachable under another domain as well to prevent a redirect loop.

I’ve also noticed that the DNS record for the developer site points to an OpenShift instance. I have no experience with it, but I think that it might be possible to configure the reditect there in a more efficient manner.

I spent some time to get comfortable with GTK naming conventions. Now, I have to re-learn several things. For test purpose, I tried to find a useful function pango_cairo_show_layout on this page: https://docs.gtk.org/PangoCairo/index.html but I could not.

The fulltext search has helped, the function is found, and it is listed on the page above, but under a different name: show_layout, i.e. without the prefix. I see that the prefix is redundant. But now I must operate with two different types/sets of function names, with and without prefixes. The word PangoLayout in the description does not work as a link anymore. However we get a link to the source code of the function. There are losses, there are wins…

BTW, what will happen to doc packages that are installed locally from a repo? Would they be updated, and if yes, then regarding the content only, or the representation too?

Thank you, person that made the automatic redirection to old docs!

All of the internal links in the old documentation are broken, too.

Also a number of projects hosted their documentation on the old developer website, and while they generally host more up-to-date documentation elsewhere, they are no longer covered by a de facto universal search like the old website provided. Basically the search function on the new developer website should be more comprehensive than it is now.