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:
- libraries hosted on gitlab.gnome.org will have to provide their own API reference
- all the libraries in the GNOME SDK will have their documentation published starting from the
org.gnome.Sdk.Docsrun time extension
Any 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:
- https://gitlab.gnome.org/robots.txt
- https://gitlab.com/robots.txt
- https://github.com/robots.txt (just for comparison)
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).
1 Like
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.
1 Like
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:
- GLib is a low level C API, with insufficient introspection data that can be used to generate the documentation
- GLib, GObject, and GIO are still using gtk-doc as their documentation generator, and haven’t been ported to gi-docgen
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.
the second issue, sadly, 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; which means GLib cannot depend on gobject-introspection, which means it cannot use gi-docgen.
A temporary option may be to generate the API reference in gobject-introspection? With the caveat that it’ll only get updated when someone runs the update-glib-annotations.py script …
That wouldn’t really solve the problem: distributions still want to provide a “docs” package out of GLib.
Having gobject-introspection, or a separate project, building the docs would still require fixing all the GLib docs in the same way we fixed GTK, and removing the ability to generate the API reference out of GLib.
Fair enough. A man can dream 
1 Like
And now I must add the suffixes and do it very consciously, because the ‘real’ functions in the source code need them. For me personally, the new schema means switching between two sets of names and additional efforts. However it gives a look of an OOP language.
That wouldn’t really solve the problem: distributions still want
to provide a “docs” package out of GLib.
We could always unify the whole of GTK as one giant package
including all necessary bits - atk, glib, pango etc… all
in a single repository and developed jointly. Then they’d
all have a single huge docs repository. 
Anyway, not really fully suggesting it as such.
I don’t mind the deprecation of old doc-related stuff. I think
the more important issue is whether people can find what they
want, how useful it is, and so on and so forth. I personally
seem to benefit the most from StackOverflow and reading
example code written by others (and ideally documented/commented).
For a docu-repository, I would ideally prefer just a single
website that includes literally all I may need. So I’d be
fine for a single GTK+GNOME website too. I rather dislike
having to go to different websites and compile together the
documentation I need, even if I do this already (I store
useful things into local files - that way I can just
look up quickly when I solved something, via my own files).
I guess ideally we could even have APIs such as:
gtk3/
gtk4/
for the homepage, to lookup specific gtk-related documentation.
And have a unified layout too.
I also like the default layout provided by https://readthedocs.org/
but I have to admit that I rarely read everything. I more read
a bit, learn something then move on again, so I take new information
in smaller bits. Not sure how many other people do that; some can
read quickly for a longer time. I fatigue early on - my brain just
is not made for long, tedious work. 
So overall I think this is a good idea. I read your comments on the
blog but I think you are too concerned about backwards
compatibility. If it is important I am sure people may point
out what they may need or want. One reason why I think
read-the-docs is good is because I read the pygobject examples
and adapted most of them into ruby-gtk (which works fine;
most examples are part of the ruby-gtk tarball, but not all
of them, so the pygobject specific parts were helpful).
This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.