GNOME Bugzilla – Bug 785522
User help documentation on developer.|help.gnome.org not updated for CMake/meson projects; Users hit 404s due to missing recent versions
Last modified: 2018-09-24 10:56:02 UTC
https://help.gnome.org/users/evolution/3.24/ does not even exist. (Maybe related to using CMake?) https://help.gnome.org/users/evolution/3.22/ is the last stable version. I do not know which version https://help.gnome.org/users/evolution/unstable/ actually displays.
(Hi Andre!) > (Maybe related to using CMake?) Indeed; help.gnome.org only knows about autotools (it looks for @YELP_HELP_RULES@ in files named Makefile.am).
Any way I can help with this? All those projects which move to meson (not CMake) will be also affected, no? Like epiphany, which is meson since 3.26 and the https://help.gnome.org/users/epiphany/ ends with 3.24.2 at the moment, even there had been 3.26 releases done already.
Indeed all non-autotools modules are affected. https://git.gnome.org/browse/library-web/tree/src/lgo.py#n700 should be updated to detect other cases, like looking for "set(HELPID" in CMakeLists.txt files, or help_files in meson.build. Then https://git.gnome.org/browse/library-web/tree/src/modtypes/mallard.py#n240 should be changed to get the list of mallard files from those CMakeLists.txt/meson.build files. (alternatively it could just take pages and figures and list of languages looking at the filesystem but then it may fail with pages/languages that are present in git but not supposed to be used). This is still relatively simple (especially compared to the gtk-doc situation).
(In reply to Frederic Peters from comment #3) > This is still relatively simple (especially compared to the gtk-doc > situation). Yup, it sounds like that. Is there a way to test the scripts locally? Though I'm not a python guy, which is sort of obstacle.
I just noticed that developer.gnome.org is also affected. See for example: https://developer.gnome.org/epiphany/ it's more than ancient (3.6.1). Similarly some eds parts: https://developer.gnome.org/libedata-book/ (3.10.2 is the latest there). Evolution composer ends at a similar time as the help (3.22.2): https://developer.gnome.org/evolution-mail-composer/
There is an additional and trickier problem for API references: cmake/meson don't create tarballs with the generated HTML files.
Oh, do you read the info from the released tarballs, not from the sources? Actually, it makes sense you use tarballs, in that case you can reference exact version, instead of guessing correct tag name or anything like that. I just didn't think about it. Would it be doable to cooperate with gnome-continuous to get the help/developer-help from there instead? Or with release-team and its BuildStream results? I mean, if the machine responsible to get the HTML files cannot configure and compile on its own, which it surely shouldn't do, because it would be another place where the hints for proper configure tools and build options would go (duplication is bad). The cooperation might be interesting, because you could get what `make install` generated in the predefined folders for the project and that's all. No need to even think of getting anything from the configuration scripts, whichever configuration application the project would use (autotools/CMake/Meson/waf/...). The only thing is that the sites will have some hints for the parts of the project, right? Like when evolution-data-server generates no help, but for developers it does in /usr/share/gtk-doc/html/ 'camel' and 'evolution-data-server' parts and evolution itself has 'evolution-mail-composer', 'evolution-mail-engine', 'evolution-mail-formatter', 'evolution-shell' and 'evolution-util' parts for developers and /usr/share/help/C/evolution/ as its help (with various other localizations).
> Would it be doable to cooperate with gnome-continuous to get the help/developer-help from there instead? Or with release-team and its BuildStream results? Indeed that's the goal (I think it is written down in another bug report but I don't have the number handy).
*** Bug 794332 has been marked as a duplicate of this bug. ***
Would it be possible, as an interim solution, to add some tool (similar to `ftpadmin install`) somewhere, where I'd be able to provide manually packed .tar.xz with an installed structure /usr/share/... which would contain the user help and developer documentation and this tool will copy it to the right places on the server and make it available on the pages? It seems to be non-trivial to achieve the goal at the moment (otherwise, I guess, it would be already fixed), thus the interim solution will give a chance to provide an up-to-date documentation to the users and developers, until it's properly fixed.
GTK+ has something similar, thay can now upload "documentation tarballs" (https://download.gnome.org/docs/gtk+/3.93/) and they are found by developer.gnome.org (it still wouldn't work as is for cmake, but that's "just" some detection code to add). However I don't know about the process to get them on the server. Back to CMake I had a look at evolution and evolution-data-server and it looks like searching for add_gtkdoc in a CMakeLists.txt file would work to find documentation modules. I can add this but for testing, could you push somewhere {camel,evolution-data-server}-x.y.z.tar.xz with docs/reference/{camel,evolution-data-server}/{html,images}/ ?
I just pushed. commit 1a734af6ebcb0415ccfa198d7f2a758630df391f Author: Frédéric Péters <fpeters@0d.be> Date: Fri Apr 6 09:29:40 2018 +0200 add experimental support for detecting documentation parts in CMake modules https://bugzilla.gnome.org/show_bug.cgi?id=785522
(In reply to Frederic Peters from comment #11) > Back to CMake I had a look at evolution and evolution-data-server and it > looks like searching for add_gtkdoc in a CMakeLists.txt file would work to > find documentation modules. Right. The only downside is that it's specific to evolution-data-server and evolution, it's nothing generic, which is a pita here. Maybe you'd have better luck by traverse of the source directory structure, rather than build scripts. I do not know whether Meson builds can also suffer of anything like that (like whether the developers can rename certain variables/functions/constructions, which would cause breakage of the search on the help/devel-doc side). > ... could you push somewhere... Sure thing. Here it is: https://people.gnome.org/~mcrha/gn785522/ Those with 'build' suffix are the files in the build directory, minus CMake files. Those with 'install' suffix are the files in my PREFIX, after `make install`. The evo help doesn't have build part, because there's no C directory in it, there are only directories for the other languages.
Sorry for the annoyance, could you do that for 3.28.0 (library-web is a bit picky about version numbers and need to start from an existing source tarball)?
(In reply to Frederic Peters from comment #14) > Sorry for the annoyance, could you do that for 3.28.0 (library-web is a bit > picky about version numbers and need to start from an existing source > tarball)? No problem, just refresh the page. The content matches build/built files of the 3.28.0 release. You know I manually made those tarballs, with "artificial" directory structure, which reflects reality, but not precisely (I build "out of source tree", in _build/ directory made inside the source tree), do you not? I'm just mentioning it, just in case it's important.
I'm sorry for the ping, but Evolution received a bug [1] which is due to this bug. I guess you didn't find time for any progress on this, did you? The change from comment #12 doesn't seem to help, because for example https://help.gnome.org/users/evolution/ still mentions 3.22.2 as the latest version. Maybe this is more important only for Evolution help, because it opens correct (based on the Evolution version) help page when the help is not installed locally (see [1]). It's great that people try to look in the help before asking, but they can face this obstacle. I can change Evolution to reference https://help.gnome.org/users/evolution/stable/ , but I hesitate to do it, because it can show "too new" help content for older versions which might not have the right features or can look differently. [1] https://gitlab.gnome.org/GNOME/evolution/issues/129
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/Infrastructure/Websites/issues/224.