Is it possible to change the HTML theme used by GtkDoc?
Not without shipping your own CSS and overwriting the existing one. The styling is an implementation detail, and it’s not documented.
I also want to point out that gtk-doc is currently unmaintained.
Thank you, Emmanuele. Any basic hint on how I could do it?
Yes, I thought so after seeing the changes in GNOME’s documentation. Well, the important thing is being able to document the code at this point, the engine can be changed later.
However personally I find the old output format more functional (like the one in developer-old.gnome.org, to be clear), while I find it stressing to read the documentation of interfaces that exist only in the new format (like Adwaita).
For me the biggest regression in the new format in terms of usability is the fact that everything by default is collapsed and I cannot search for strings in the page unless I look at the HTML source code or I expand the elements manually – but that means that I have already found them.
Addition. When they are not collapsed, things tend to be nested in sub-pages, and that makes the reading more complicated too.
You have to replace style.css in the output directory with your own; you can look at the contents of the style directory which get copied to the HTML output.
The collapsed/uncollapsed is going to be solved by having an “expand all” button in the future; I just haven’t had time to implement it yet.
Dumping the entirety of the API into a single page is a massive mistake, and makes the documentation unusable for people who are not already familiar with it. “Searching in the page” is actually an anti-pattern, and an indication that the page is too big to begin with. The proper way to find things is to search using the search entry in the side bar, which does a (fuzzy) full text search in the entire reference.
Ok, got it. Thank you.
I don’t know, I guess nothing is so black and white. Doxygen does that, and most manuals of the GNU project offer the possibility to choose between two formats, a single HTML page and one HTML page for each chapter.
A rule of thumb for me in those cases is this: If it is a new topic I prefer to have one HTML page per topic, whereas if it is instead something I am familiar with I prefer to have a huge book in one single page and use it as a reference book, scrolling around.
There is one thing that people are familiar with for sure, and that is their browser. If I read something in a website (any website) and I find something rememberable there, it is automatic for me next time I visit to press Ctrl+F and search in the page. Any other search engine instead I will have to learn how it behaves.
An opposite example is the Discourse platform, which I find fantastic in general, but has the big problem that overrides my browser Ctrl+F (I just checked and it doesn’t do it on discourse.gnome.org). Normally in front of that I use the menu bar and I still use my browser for searching in the page.
―madmurphy
This topic was automatically closed 45 days after the last reply. New replies are no longer allowed.