It’s way more difficult / less intuitive for me 
I’m feeling dumb.
I never would think that the API would in “an overview” of “platform components”.
Anyway, I couldn’t find the gtkmm docs (API and tutorials), and we have students in the middle of GSOC 
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.
Yes, it’s faded in the first post of this hidden forum 
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.
Hello! Just saying, what about keeping the good ol’ documentation in developer.gnome.org as always (maybe with some restyling) and have a different URL for the new reference documentation? Say reference.gnome.org…
Ah, got it.
Thanks
To be fair, it was already broken, as library-web and gtk-doc have had issues with cross-references for ages. It used to work years ago, but the introduction of multiple major versions of GTK broke all the cross-references to GDK, as an example.
In any case, I recommend reading my blog about why this change was necessary and what is going to happen in the near future.
The “universal search” being Google? Because the internal search provided by library-web barely worked.
If you mean cross-namespace searches, then it’s unlikely to happen—unless, of course, people want to contribute to it.
In practice, though, two things are going to happen:
org.gnome.Sdk.Docs run time extensionAny further improvement is predicated on these two steps.
I do hope that somebody else will consider working on the developers documentation in the future; considering the amount of contributions that have happened in the past 10 years, I am not going to hold my breath—but stranger things have happened.
In the meantime, I strongly recommend that if people wish to see more actual content that is not related to API references, they start writing tutorials and guides.
Since the API references that have been published on the old developer.gnome.org and on docs.gtk.org come from each project, local installations will look exactly the same as the documentation provided by those websites.
Something seems to have more-recently broken, because https://developer.gnome.org/hig/stable/ is now a 404. Home - GNOME User Interface Guidelines documentation works, to reach the HIG, but it no longer appears to be /stable/ (which suddenly takes on a double meaning).
(Frickin’ Discourse. What I said was, https://developer.gnome.org/hig/ works, to reach the HIG.)
Yes, the design team asked to drop the “stable” bit, as there’s no “unstable” HIG.
The URLs should have been changed; if they haven’t, please: file a bug.
I was mistaken, in that most internal links do appear to work. It’s only a handful that are broken. A bit of an aside here is that the subdomain “legacy.gnome.org” might be more elegant in the long term than “developer-old.gnome.org”, though it’s somewhat less specific. Also IMHO you could add a massive banner across the top of the page on the legacy documentation specifically marking it as such.
You can create a custom search widget that pipes the search query into a site-specific search on DuckDuckGo, for example https://duckduckgo.com/?q=site%3Agnome.org+foobar. DuckDuckGo is preferable to Google for site-specific searches because DDG doesn’t track its users, which I imagine would be important for compliance with GNOME’s own privacy policy.
FWIW you could provide the option of searching all of gnome.org or just developer.gnome.org from a single search field, though how to implement that in the UI is beyond my expertise. (The search should presumably also cover docs.gtk.org if the GTK documentation isn’t going to appear on the developer.gnome.org domain as everything else.) Also you could replace the search field in the legacy documentation so that it searches all of gnome.org by default, which could help users find more up-to-date versions of things.
Notably, the site-specific DuckDuckGo search does not appear to index the GNOME Gitlab, but it does index basically every other subdomain. (DuckDuckGo uses syndicated search results from a variety of sources, most prominently Bing.) If you search for gnome gitlab on DDG, the top result is the defunct gitlab.com/gnome, with gitlab.gnome.org entirely missing, and if you search anything more specific, such as gtk "gitlab" (yes, with “gitlab” in quotes!), the GTK Gitlab repository doesn’t appear in the search results, but the GitHub mirror of the Gitlab repository *does*.
One might assume the complete omission of gitlab.gnome.org from DuckDuckGo’s search results has something to do with the robots.txt file, but it appears to be nearly identical to the main gitlab.com one:
I recognize that the SEO problem may be somewhat off-topic for this particular comment thread, but I’d be happy to repost about it on whatever issue tracker is most applicable if you can point me in the right direction.
Is there a particular process that libraries on gitlab.gnome.org (but not part of the official GNOME SDK) could follow for getting their (RST) documentation hosted by and linked from the main developer.gnome.org portal? If so, could you potentially publish that process in the documentation for the new documentation?
Also, in the interest of coherence, if the various namespaces don’t already have the same RST/Sphinx theme, could you consider facilitating having that be the default? It could also be nice if the various namespaces were to have a global header bar with a link to the developer.gnome.org homepage as well as a local/global search field and possibly URL breadcrumbs if that would make sense.
I do have some other more specific feedback that I can post on the issue tracker you linked earlier (or the more general “Initiatives” issue tracker).
The old GObject API reference manual has explanation about the concept of GObject and also a tutorial.
The new reference manual doesn’t have concept explanations and tutorals.
Are there any plan to put those things into developer documatation website?
Because the new GObject reference manual is very hard for beginners, I think it’s better to put a tutorial in somewhere in the website.
Yes. The ancillary documentation is being ported. It’s a slow process because the old documentation is written in DocBook format, while the new is in Markdown; additionally, the porting offers a chance at fixing/cleaning up the old documentation.
I’ve encountered a couple of problems with the new API documentation as
presented on the web as opposed to the old documentation. For
reference, I will use GLib – 2.0 as an
example.
The biggest problem relates to constructors. For example, under the
Structs tab I can find String. Clicking on String, I see what a String
is and how to use one. But there is no documentation on that page to
create one. Those are found in the Functions tab and are lacking the
g_ prefix. But that information should really be in the page that
describes String. As it exists, this is a major discoverability
problem.
Second, why are the g_ prefixes removed from the Functions tab? This
just makes things generally inconsistent.
Is there a reason that documentation that references to other functions
(such as the reference to g_string_printf() in the documentation for
g_string_append_printf()) are not hyperlinks? This would be a lot more
useful in this new structure where each function is on a separate page.
As a sub-comment, I think that the Structs tab should probably be
renamed to “Objects”, as that is how they are represented in the
documentation.
First of all, thanks for the feedback.
The GLib documentation is, sadly, not a representative of the intended result, for two main reasons:
For the first issue, the proper “fix” is to improve the introspection data generator; the second issue is more complicated to address. GLib should still be able to generate its API reference when built locally, but unlike gtk-doc, gi-docgen relies on the introspection data provided by a library. The introspection data is not generated by GLib itself, but by gobject-introspection; gobject-introspection itself depends on GLib, which means GLib cannot depend on gobject-introspection, which means it cannot use gi-docgen.
See this issue for more information: Strawman: Adapt documentation to gi-docgen (#2365) · Issues · GNOME / GLib · GitLab
This is one of the cases where the introspection data isn’t good enough to generate an actual representation of the API; instead of a constructor, or a method under the String class, the introspection scanner generates this:
<function name="string_new" c:identifier="g_string_new">
<doc xml:space="preserve"
filename="source/gobject-introspection/gir/glib-2.0.c"
line="32528">Creates a new #GString, initialized with the given string.</doc>
<source-position filename="install/include/glib-2.0/glib/gstring.h"
line="49"/>
<return-value transfer-ownership="full">
<doc xml:space="preserve"
filename="source/gobject-introspection/gir/glib-2.0.c"
line="32535">the new #GString</doc>
<type name="String" c:type="GString*"/>
</return-value>
<parameters>
<parameter name="init"
transfer-ownership="none"
nullable="1"
allow-none="1">
<doc xml:space="preserve"
filename="source/gobject-introspection/gir/glib-2.0.c"
line="32530">the initial text to copy into the string, or %NULL to
start with an empty string</doc>
<type name="utf8" c:type="const gchar*"/>
</parameter>
</parameters>
</function>
which is not really useful, and leads to a GLib.string_new symbol.
This issue should be fixed in GLib, but it has nothing to do with the documentation itself.
Because all symbols are prefixed with g_, just like all identifiers are prefixed with G. It’s redundant: you’re already under the GLib/GObject/GIO namespace. That’s not the important thing to visually scan for.
The only place where the symbol and identifier prefixes are important is the C declaration. If everything were prefixed by g_ and G, you’d have to unconsciously skip that bit anyway in order to find what you’re looking for.
Aside from the issue of visually scanning a sea of symbols, the other issue is that the C API reference will inevitably also serve as a backup for the references in other languages; it already happens with the reference generated by gtk-doc, so the C API reference should make it slightly easier to different consumers of the same API in other languages to find what they are looking for.
This is the gtk-doc/gi-docgen issue I was referring to at the beginning: gi-docgen uses explicit links, like: [class@Gio.Cancellable], or [func@GLib.strdup], whereas gtk-doc uses regular expressions and devhelp files to perform matches with likely candidates. The latter approach is brittle, which the potential of broken links; slow, as it requires loading a whole separate index file and do a cross-reference fix pass to the generated HTML; and leads to overlinking in the text, with every single possible instance of a type, identifier, or function getting turned into a link, which makes the documentation harder to follow.
It would be possible to turn types and functions into links, since gi-docgen does that perfectly well for the GTK4 documentation; the main issue is doing so in the GLib documentation, which is something we can’t really do unless we figure out a way to get GLib/GObject/GIO to depend on gobject-introspection and gi-docgen.
They are not objects, they are C structures—with or without a GType.
The structured types at our disposal are either classes—i.e. GTypeInstance-derived types, like GObject or GParamSpec; interfaces, derived by GTypeInterface; records, i.e. plain old data structures—likely providing a GBoxed type; or unions, i.e. C union types—also likely providing a GBoxed type.
Everything you see inside GLib is a struct, not an object, because GLib does not have access to the type system, which resides in libgobject-2.0.