GNOME Bugzilla – Bug 784209
[Regression] No more object linking
Last modified: 2018-05-13 11:49:22 UTC
While testing evolution-data-server (for bug #784182), I noticed a difference between the output of gtk-doc 1.25 and gtk-doc master (at commit 0b348f6). There are no more object linking in the output. I'm attaching two files for comparison, both had been built with the same source code of evolution-data-server, only gtk-doc version changed. See that the 1.25 has linked (clickable) EExtension strings, while the git-master generated HTML does not.
Created attachment 354499 [details] gtk-doc 1.25 output
Created attachment 354500 [details] git master output
Will check, could you also attach the docbook xml files? I've tested with projects like glib, gstreamer etc. so far and did not notice missing links.
Created attachment 354579 [details] docs.sgml I guess you mean this file. I compared it with the generated file from git master and they are the same. That led me to compare also the attached files (diff -up) and it showed me, beside other changes which might be interesting for you too, that 1.25 generates real anchors: <a class="link" href="evolution-data-server-EExtension.html#EExtension" title="struct EExtension"><span class="type">EExtension</span></a> while git master generates: <GTKDOCLINK HREF="EExtension"><span class="type">EExtension</span> </GTKDOCLINK> I opened the files in a web browser, as they are HTML pages after all, and the browser doesn't understand the new tag, of course, thus it can be my fault expecting the two versions behaving exactly the same (generating exactly the same HTML code).
Indeed there are <GTKDOCLINK HREF=...>...</GTKDOCLINK> entries left. There must be something special with your project setup though, that make gtkdoc-fixxref not processing them (gtkdoc-fixxref is resolving those links). Can you please attach a logfile: GTKDOC_TRACE=debug make >debug.log 2>&1
Created attachment 354625 [details] shorterlog.txt It is called this way: https://git.gnome.org/browse/evolution-data-server/tree/cmake/modules/GtkDoc.cmake#n87 The resulting log file has over 70MB (with `make VERBOSE=1', and over 40MB with plain 'make') and compressed like 1.6MB for the 40MB size. What exactly are you looking for? See the attached portion, I tried to extract parts around that EExtension structure, but I might miss something important. I noticed also lines like this one: > 2017-06-28 14:53:53,651:fixxref.py:Run:95:INFO:Scanning HTML_DIR directory: > /my/custom/prefix/share/gtk-doc/html/evolution-data-server That doesn't feel correct, because it's my PREFIX, the place I'm installing to, but you are reading files from there before they were written, thus either the directory is nonexistent, or it contains old data. A brief checkout on the difference between with and without that directory didn't show any relevant change (or I simply didn't notice it). There is also a guide how to compile evolution-data-server, maybe you'll find it useful for easier reproducer: https://wiki.gnome.org/Apps/Evolution/Building
Are those cmake modules the same we ship with gtkdoc? I really don't know much about cmake :/ I can't repro it myself, I am stuck on ubuntu trusty for now (company laptop).
To debug this, you can look at the log and grep for "fixxref.py". In your attached log, I can't see lines saying "Fixing file:". The makefiles and our cmake support call fixxref as gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html ... you seem to pass --module-dir=. The html files are not scanned recursively. Could you consider switching to the cmake support we ship with gtk-doc?
Right, I made that cmake file based on the commands being invoked when using autotools, I do not recall which version the gtk-doc was when I did that. I did consider using the cmake module provided by gtk-doc in that time, but there didn't work something, or it was too complicated to use, or even just too new to bump dependency version on gtk-doc, I do not recall precisely why I didn't use it at the end, I'm sorry. (In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #8) > To debug this, you can look at the log and grep for "fixxref.py". In your > attached log, I can't see lines saying "Fixing file:". Right, there is no such text in the 70MB log. > The makefiles and our cmake support call fixxref as > gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html ... > you seem to pass --module-dir=. The html files are not scanned recursively. I see. With that change it shows the "Fixing file" lines, but it doesn't find the EExtension (see the log snippet below). > Could you consider switching to the cmake support we ship with gtk-doc? Right, I can reconsider it and it would make perfect sense, of course (better to reuse the code, than to develop the same thing myself, not talking about maintainability with changes on the gtk-doc side). I need to test it first, though. > 2017-06-29 09:20:44,561:fixxref.py:FixHTMLFile:221:INFO:Fixing file: html/evolution-data-server-EExtensible.html > ... > 2017-06-29 09:20:44,580:fixxref.py:MakeXRef:299:INFO:Fixing link: GList, /usr/share/gtk-doc/html/glib/glib-Doubly-Linked-Lists.html#GList, <span class="returnvalue">GList</span> > 2017-06-29 09:20:44,580:fixxref.py:MakeXRef:302:INFO:no link for: EExtension, <span class="type">EExtension</span>
One thing I do not understand, why does it work with 1.25, but not with git master? I saw somewhere a mentioning that the rewrite to python was 1:1. Or maybe I just misremember.
Just from a quick glance, GtkDocConfig.cmake provides gtk_doc_add_module() function. That doesn't let me define --deprecated-guards=. There is also no install() there, which feels odd, but I do not know how that works, thus maybe it's correct. The documentation for gtk_doc_add_module() is also inaccurate (read from the GtkDocConfig.cmake), it says that the first argument is 'doc_prefix', then it shows at the end an example call: gtk_doc_add_module(doc-mymodule but the result is that the newly created target is named: doc-doc-mymodule aka you add your own "doc-" prefix to my module name. I had my targets named "gtkdoc-module", which I also passed to this function, but it resulted in CMake failure. Another problem is with the set(GTKDOC_SCAN_EXE ${exec_prefix}/bin/gtkdoc-scan) This is wrong. My exec_prefix is not defined, thus it results in /bin/gtkdoc-scan which means to use the system-wide gtk-doc, but I have installed system gtk-doc, with my own gtk-doc compiled into my prefix. Not having installed system-wide gtk-doc results in error about missing files. I changed it to find_program(GTKDOC_SCAN_EXE gtkdoc-scan) and similarly those other using exec_prefix in the GtkDocConfig.cmake provided by gtk-doc. My version doesn't scan object files, it scans sources. This doesn't seem to be possible with the provided CMake file, right? So I passed it this: gtk_doc_add_module(${_module} SOURCE ${_srcdirs} XML "${CMAKE_CURRENT_BINARY_DIR}/${_module}-docs.sgml" IGNORE_HEADERS ${${_ignoreheadersvar}} LIBRARIES edataserver LIBRARY_DIRS ${CMAKE_BINARY_DIR}/src/libedataserver DEPENDS ${_filedeps} ) where the _module=evolution-data-server and it fails with a gcc error (without LIBRARIES and LIBRARY_DIR it fails with missing symbols, which is expected): > [ 38%] Generating evolution-data-server/evolution-data-server.signals > cd /my/sources/evolution-data-server/_build/docs/reference/evolution-data-server/evolution-data-server && /usr/bin/cmake -D GTKDOC_SCANGOBJ_EXE:STRING=/my/prefix/bin/gtkdoc-scangobj -D doc_prefix:STRING=evolution-data-server -D output_types:STRING=/my/sources/evolution-data-server/_build/docs/reference/evolution-data-server/evolution-data-server/evolution-data-server.types -D output_dir:STRING=/my/sources/evolution-data-server/_build/docs/reference/evolution-data-server/evolution-data-server -D "EXTRA_CFLAGS:STRING=-I/my/prefix/include/libsoup-2.4;-I/my/sources/evolution-data-server/_build;-I/my/sources/evolution-data-server/_build/src;-I/my/sources/evolution-data-server/_build/src/libedataserver;-I/my/sources/evolution-data-server/_build/src/private;-I/my/sources/evolution-data-server/src;-I/my/sources/evolution-data-server/src/private;-I/usr/include/at-spi-2.0;-I/usr/include/at-spi2-atk/2.0;-I/usr/include/atk-1.0;-I/usr/include/cairo;-I/usr/include/dbus-1.0;-I/usr/include/freetype2;-I/usr/include/gck-1;-I/usr/include/gcr-3;-I/usr/include/gdk-pixbuf-2.0;-I/usr/include/gio-unix-2.0/;-I/usr/include/glib-2.0;-I/usr/include/gtk-3.0;-I/usr/include/harfbuzz;-I/usr/include/json-glib-1.0;-I/usr/include/libdrm;-I/usr/include/libpng16;-I/usr/include/libsecret-1;-I/usr/include/libxml2;-I/usr/include/nspr4;-I/usr/include/nss3;-I/usr/include/p11-kit-1;-I/usr/include/pango-1.0;-I/usr/include/pixman-1;-I/usr/include/webkitgtk-4.0;-I/usr/lib64/dbus-1.0/include;-I/usr/lib64/glib-2.0/include;-pthread;E_DATA_SERVER_CREDENTIALMODULEDIR=\"/my/prefix/lib/evolution-data-server/credential-modules\";E_DATA_SERVER_IMAGESDIR=\"/my/prefix/share/pixmaps/evolution-data-server\";E_DATA_SERVER_LOCALEDIR=\"/my/prefix/share/locale\";E_DATA_SERVER_PREFIX=\"/my/prefix\";E_DATA_SERVER_PRIVDATADIR=\"/my/prefix/share/evolution-data-server\";G_LOG_DOMAIN=\"e-data-server\";LIBEDATASERVER_COMPILATION" -D "EXTRA_LDFLAGS:STRING=/my/sources/evolution-data-server/_build/src/libedataserver/libedataserver-1.2.so.22.0.0;-l-L/my/prefix/lib;-l-Wl,--export-dynamic;-l-latk-1.0;-l-lcairo;-l-lcairo-gobject;-l-ldl;-l-lgck-1;-l-lgcr-base-3;-l-lgdk-3;-l-lgdk_pixbuf-2.0;-l-lgio-2.0;-l-lglib-2.0;-l-lgmodule-2.0;-l-lgobject-2.0;-l-lgtk-3;-l-licudata;-l-licui18n;-l-licuuc;-l-ljavascriptcoregtk-4.0;-l-ljson-glib-1.0;-l-lnspr4;-l-lnss3;-l-lnssutil3;-l-lp11-kit;-l-lpango-1.0;-l-lpangocairo-1.0;-l-lplc4;-l-lplds4;-l-lpthread;-l-lsecret-1;-l-lsmime3;-l-lsoup-2.4;-l-lssl3;-l-lwebkit2gtk-4.0;-l-lxml2;-l-pthread;-lcamel;-ledataserver-private;-ledbus-private" -D EXTRA_LDPATH:STRING=/my/sources/evolution-data-server/_build/src/libedataserver -P /my/prefix/lib/cmake/GtkDoc/GtkDocScanGObjWrapper.cmake > -- Found PkgConfig: /usr/bin/pkg-config (found version "0.29.1") > -- Checking for modules 'glib-2.0;gobject-2.0' > -- Found glib-2.0, version 2.50.3 > -- Found gobject-2.0, version 2.50.3 > -- Executing gtkdoc-scangobj with: > -- CFLAGS: -g -O0 -Wall -Wno-deprecated-declarations "-I/my/prefix/include/libsoup-2.4" "-I/my/sources/evolution-data-server/_build" "-I/my/sources/evolution-data-server/_build/src" "-I/my/sources/evolution-data-server/_build/src/libedataserver" "-I/my/sources/evolution-data-server/_build/src/private" "-I/my/sources/evolution-data-server/src" "-I/my/sources/evolution-data-server/src/private" "-I/usr/include/at-spi-2.0" "-I/usr/include/at-spi2-atk/2.0" "-I/usr/include/atk-1.0" "-I/usr/include/cairo" "-I/usr/include/dbus-1.0" "-I/usr/include/freetype2" "-I/usr/include/gck-1" "-I/usr/include/gcr-3" "-I/usr/include/gdk-pixbuf-2.0" "-I/usr/include/gio-unix-2.0/" "-I/usr/include/glib-2.0" "-I/usr/include/gtk-3.0" "-I/usr/include/harfbuzz" "-I/usr/include/json-glib-1.0" "-I/usr/include/libdrm" "-I/usr/include/libpng16" "-I/usr/include/libsecret-1" "-I/usr/include/libxml2" "-I/usr/include/nspr4" "-I/usr/include/nss3" "-I/usr/include/p11-kit-1" "-I/usr/include/pango-1.0" "-I/usr/include/pixman-1" "-I/usr/include/webkitgtk-4.0" "-I/usr/lib64/dbus-1.0/include" "-I/usr/lib64/glib-2.0/include" "-pthread" "E_DATA_SERVER_CREDENTIALMODULEDIR="/my/prefix/lib/evolution-data-server/credential-modules"" "E_DATA_SERVER_IMAGESDIR="/my/prefix/share/pixmaps/evolution-data-server"" "E_DATA_SERVER_LOCALEDIR="/my/prefix/share/locale"" "E_DATA_SERVER_PREFIX="/my/prefix"" "E_DATA_SERVER_PRIVDATADIR="/my/prefix/share/evolution-data-server"" "G_LOG_DOMAIN="e-data-server"" "LIBEDATASERVER_COMPILATION" "-I/usr/include/glib-2.0" "-I/usr/lib64/glib-2.0/include" > -- LDFLAGS: -Wl,--as-needed -Wl,-z -Wl,relro -Wl,-z -Wl,now -Wl,-z -Wl,defs -Wl,--as-needed -Wl,-z,now "/my/sources/evolution-data-server/_build/src/libedataserver/libedataserver-1.2.so.22.0.0" "-l-L/my/prefix/lib" "-l-Wl,--export-dynamic" "-l-latk-1.0" "-l-lcairo" "-l-lcairo-gobject" "-l-ldl" "-l-lgck-1" "-l-lgcr-base-3" "-l-lgdk-3" "-l-lgdk_pixbuf-2.0" "-l-lgio-2.0" "-l-lglib-2.0" "-l-lgmodule-2.0" "-l-lgobject-2.0" "-l-lgtk-3" "-l-licudata" "-l-licui18n" "-l-licuuc" "-l-ljavascriptcoregtk-4.0" "-l-ljson-glib-1.0" "-l-lnspr4" "-l-lnss3" "-l-lnssutil3" "-l-lp11-kit" "-l-lpango-1.0" "-l-lpangocairo-1.0" "-l-lplc4" "-l-lplds4" "-l-lpthread" "-l-lsecret-1" "-l-lsmime3" "-l-lsoup-2.4" "-l-lssl3" "-l-lwebkit2gtk-4.0" "-l-lxml2" "-l-pthread" "-lcamel" "-ledataserver-private" "-ledbus-private" "-lgobject-2.0" "-lglib-2.0" > -- LDPATH: /my/sources/evolution-data-server/_build/src/libedataserver > gcc: error: E_DATA_SERVER_CREDENTIALMODULEDIR=/my/prefix/lib/evolution-data-server/credential-modules: No such file or directory > gcc: error: E_DATA_SERVER_IMAGESDIR=/my/prefix/share/pixmaps/evolution-data-server: No such file or directory > gcc: error: E_DATA_SERVER_LOCALEDIR=/my/prefix/share/locale: No such file or directory > gcc: error: E_DATA_SERVER_PREFIX=/my/prefix: No such file or directory > gcc: error: E_DATA_SERVER_PRIVDATADIR=/my/prefix/share/evolution-data-server: No such file or directory > gcc: error: G_LOG_DOMAIN=e-data-server: No such file or directory > gcc: error: LIBEDATASERVER_COMPILATION: No such file or directory > Traceback (most recent call last): > File "/my/prefix/bin/gtkdoc-scangobj", line 71, in <module> > sys.exit(scangobj.run(options)) > File "/my/prefix/share/gtk-doc/python/gtkdoc/scangobj.py", line 1255, in run > res = subprocess.check_call(command, shell=True) > File "/usr/lib64/python2.7/subprocess.py", line 186, in check_call > raise CalledProcessError(retcode, cmd) > subprocess.CalledProcessError: Command '/usr/bin/gcc >/dev/null -g -O0 -Wall -Wno-deprecated-declarations "-I/my/prefix/include/libsoup-2.4" "-I/my/sources/evolution-data-server/_build" "-I/my/sources/evolution-data-server/_build/src" "-I/my/sources/evolution-data-server/_build/src/libedataserver" "-I/my/sources/evolution-data-server/_build/src/private" "-I/my/sources/evolution-data-server/src" "-I/my/sources/evolution-data-server/src/private" "-I/usr/include/at-spi-2.0" "-I/usr/include/at-spi2-atk/2.0" "-I/usr/include/atk-1.0" "-I/usr/include/cairo" "-I/usr/include/dbus-1.0" "-I/usr/include/freetype2" "-I/usr/include/gck-1" "-I/usr/include/gcr-3" "-I/usr/include/gdk-pixbuf-2.0" "-I/usr/include/gio-unix-2.0/" "-I/usr/include/glib-2.0" "-I/usr/include/gtk-3.0" "-I/usr/include/harfbuzz" "-I/usr/include/json-glib-1.0" "-I/usr/include/libdrm" "-I/usr/include/libpng16" "-I/usr/include/libsecret-1" "-I/usr/include/libxml2" "-I/usr/include/nspr4" "-I/usr/include/nss3" "-I/usr/include/p11-kit-1" "-I/usr/include/pango-1.0" "-I/usr/include/pixman-1" "-I/usr/include/webkitgtk-4.0" "-I/usr/lib64/dbus-1.0/include" "-I/usr/lib64/glib-2.0/include" "-pthread" "E_DATA_SERVER_CREDENTIALMODULEDIR="/my/prefix/lib/evolution-data-server/credential-modules"" "E_DATA_SERVER_IMAGESDIR="/my/prefix/share/pixmaps/evolution-data-server"" "E_DATA_SERVER_LOCALEDIR="/my/prefix/share/locale"" "E_DATA_SERVER_PREFIX="/my/prefix"" "E_DATA_SERVER_PRIVDATADIR="/my/prefix/share/evolution-data-server"" "G_LOG_DOMAIN="e-data-server"" "LIBEDATASERVER_COMPILATION" "-I/usr/include/glib-2.0" "-I/usr/lib64/glib-2.0/include" -c -o evolution-data-server-scan.o evolution-data-server-scan.c' returned non-zero exit status 1 > CMake Error at /my/prefix/lib/cmake/GtkDoc/GtkDocScanGObjWrapper.cmake:62 (message): > Scan failed. So I disabled the call to gtkdoc-scangobj (by removing dependency on ${_output_signals}). It resulted in another error: > [ 40%] Generating HTML documentation for evolution-data-server module with gtkdoc-mkhtml > cd /my/sources/evolution-data-server/_build/docs/reference/evolution-data-server && /usr/bin/cmake -E copy /my/sources/evolution-data-server/_build/docs/reference/evolution-data-server/evolution-data-server-docs.sgml /my/sources/evolution-data-server/_build/docs/reference/evolution-data-server/evolution-data-server/evolution-data-server-docs.xml > cd /my/sources/evolution-data-server/_build/docs/reference/evolution-data-server && cd /my/sources/evolution-data-server/_build/docs/reference/evolution-data-server/evolution-data-server/html && /my/prefix/bin/gtkdoc-mkhtml evolution-data-server /my/sources/evolution-data-server/_build/docs/reference/evolution-data-server/evolution-data-server/evolution-data-server-docs.xml > /my/sources/evolution-data-server/_build/docs/reference/evolution-data-server/evolution-data-server/xml/e-source.xml:7: warning: failed to load external entity "/my/sources/evolution-data-server/_build/docs/reference/evolution-data-server/evolution-data-server/xml/gtkdocentities.ent" > %gtkdocentities; >... > docs/reference/evolution-data-server/CMakeFiles/doc-evolution-data-server.dir/build.make:404: recipe for target 'docs/reference/evolution-data-server/evolution-data-server/html.stamp' failed > make[2]: *** [docs/reference/evolution-data-server/evolution-data-server/html.stamp] Error 6 > make[2]: *** Deleting file 'docs/reference/evolution-data-server/evolution-data-server/html.stamp' Note of the doubled "evolution-data-server/evolution-data-server/xml/gtkdocentities.ent" in the path, that looks suspicious. When going into that directory I see this generated structure: /my/sources/evolution-data-server/_build/docs/reference/evolution-data-server CMakeFiles (directory) cmake_install.cmake CTestTestfile.cmake evolution-data-server (directory) dir.stamp evolution-data-server-decl.txt evolution-data-server-docs.xml evolution-data-server-overrides.txt evolution-data-server-sections.txt evolution-data-server.types evolution-data-server-undeclared.txt evolution-data-server-undocumented.txt evolution-data-server-unused.txt html (directory) html_dir.stamp sgml.stamp xml (directory) evolution-data-server-docs.sgml Makefile I do not know how to move forward with those missing gtkdocentities files, thus I stopped my testing of the gtk-doc-provided CMake function.
Created attachment 354675 [details] git master output with --module-dir=html to fixxref I reverted my changes from trying the file provided by gtk-doc and rerun with the fix you suggested and this is the result. Notice that EExtension type is not linkified, while glib types like GList and GObject are (together with some other macros). I do not know whether it's a good idea to fix href in this stage, in the build time, because for example in Fedora I have installed developer-package for glib2, but not the package which contains the documentation, which means that the resulting documentation of evolution-data-server will not have linkified glib types even if the user installing developer documentation for eds has also installed glib's developer documentation.
I re-run also with gtk-doc 1.25 with that change to fixxref and it produces exactly the same file as I attached above (the first attachment for gtk-doc 1.25), thus I'm committing at least this change to eds.
(In reply to Milan Crha from comment #10) > One thing I do not understand, why does it work with 1.25, but not with git > master? I saw somewhere a mentioning that the rewrite to python was 1:1. Or > maybe I just misremember. Hej, sure it is supposed to be a 1:1 rewrite, but please understand that it is a lot of perl code and there might be subtle differences. I am happy to fix them in the python port if we know what exactly is not working. For the fixxref path change, I can't see why this would have worked before. I double checked: https://git.gnome.org/browse/gtk-doc/tree/gtkdoc-fixxref.in?h=GTK_DOC_1_25#n320 and this is not recursively fixing files before either. If "EExtension type is not linkified" then ScanIndices() is not reading the *.devhelp2 file (or the legacy index.sgml) that contains it. This would be the next thing to check.
Created attachment 354722 [details] 1.25 git master diff of the .devhelp2 file (In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #14) > Hej, sure it is supposed to be a 1:1 rewrite, but please understand that it > is a lot of perl code and there might be subtle differences. Right right, I didn't mean any offence, I've been only wondering. It's understood that different language causes different behaviour (tell me about that). :) > If "EExtension type is not linkified" then ScanIndices() is not reading the > *.devhelp2 file (or the legacy index.sgml) that contains it. This would be > the next thing to check. Aaah, it's not part of the .devhelp2 file at all. See the attached diff which shows what had been removed from it when using git master of gtk-doc (the previous had been created with the 1.25 release). Many structures are missing, but not only structures. Both files had been generated on eds at commit_6c715e7, the only change was gtk-doc version.
Can you make a tarball of the intermediate files with 1.25 and git? Those are the files in your doc dir starting with the DOC_MODULE name, e.g. if DOC_MODULE=tester: tester.args tester-decl-list.txt tester-decl.txt tester-docs.xml tester.hierarchy tester.interfaces tester-overrides.txt tester.prerequisites tester-sections.txt tester.signals tester.types tester-undeclared.txt tester-undocumented.txt tester-unused.txt
Created attachment 354822 [details] gtkdoc files, as .tar.xz The $ diff -upr ./1.25 ./master shows that some symbols had been added, but also some removed. Note that I use exactly the same evolution-data-server here, the only thing which changes is version of gtk-doc. The gtk-doc checkout I used was at commit 0b348f6.
A few comments: 1) In master you've missed to archive the evolution-data-server-decl-list.txt. It is produced by gtkdoc-scan (see doc/gtkdoc.dot or the generated image) 2) evolution-data-server-decl.txt only has whitespace changes (the new version produces no more whitespace around symbol names, so it is better) 3) Do you generate evolution-data-server-sections.txt? Because that would explain (1) since it is moved from evolution-data-server-decl-list.txt to evolution-data-server-sections.txt, but than I wonder why the 1.25 folder has the file. This file has most of the delta and the changes indicate that your gobjects are not recognized.
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #18) > 1) In master you've missed to archive the > evolution-data-server-decl-list.txt. It is produced by gtkdoc-scan (see > doc/gtkdoc.dot or the generated image) No, that file wasn't there. > 3) Do you generate evolution-data-server-sections.txt? Yes, I generate everything except of the sgml file, which is only pre-processed during configure time: https://git.gnome.org/browse/evolution-data-server/tree/docs/reference/evolution-data-server > ...but than I wonder why the 1.25 folder has the file. This file has most > of the delta and the changes indicate that your gobjects are not recognized. Hmm, that's a question for you. Note that I do not compile the code, I let it do everything from the source code. It did work with 1.25, or I did not notice any bad side effect (maybe except of missing the type tree), which makes the documentation build being quicker (subjective measure).
Created attachment 355253 [details] buildlog.txt Here's a buildlog.txt, which contains both build logs for gtk-doc master and the 1.25 release, with the commands being run when generating the documentation and with some other output (I skipped most of those "multiple "IDs" warnings produced by gtk-doc master there, because they do not add much value). It doesn't contain the preprocessing of the .sgml file, but that's attached above. You can see full paths, thus it's also shown which gtk-doc had been used (the system-provided is the 1.25 release, namely gtk-doc-1.25-2.fc25.x86_64). It simply shows that there are called these commands in this order: gtkdoc-scan gtkdoc-mkdb `mkdir html` by cmake gtkdoc-mkhtml - from the 'html' directory gtkdoc-fixxref - from the documentation directory (parent of 'html')
A useful build log would be one with the gtkdoc info: GTKDOC_TRACE=debug make >debug.log 2>&1
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #21) > A useful build log would be one with the gtkdoc info: > GTKDOC_TRACE=debug make >debug.log 2>&1 We've been there already, see comment #5.
I've spend the last day setting up jhbuild on a new computer to be able to provide a repro: > pwd /home/ensonic/projects/gnome-jhbuild-install/share/gtk-doc/html/evolution-data-server > find . -name "*.html" -exec grep -Hn "GTKDOCLINK" {} \; > There are no GTKDOCLINK tag left in the html output though. I also compared the outputs against the stable build: # in the output dir: gnome-jhbuild-install/share/gtk-doc/html mv evolution-data-server evolution-data-server.head jhbuild shell # in gtk-doc, checkout one below GTK_DOC_1_25 (so that we get the same version 1.25.1) > git checkout 2ff3cc42717730e0e8d9724e4e455cbef2bc7199 > exit > jhbuild buildone -n --force gtk-doc > file /home/ensonic/projects/gnome-jhbuild-install/bin/gtkdoc-mkdb /home/ensonic/projects/gnome-jhbuild-install/bin/gtkdoc-mkdb: Perl script text executable > jhbuild buildone -n --force evolution-data-server # in the output dir: gnome-jhbuild-install/share/gtk-doc/html > mv evolution-data-server evolution-data-server.1.25 > diff -r -w evolution-data-server.1.25/ evolution-data-server.head/ I see some delta - mostly function that are not linkified. I'll compare the xml next too.
Created attachment 357242 [details] [review] fix symbol name Can you please check that the symbols in the doc-blob are the same as the actual symbol name. See attached patch. It could be that the perl version did an case insensitive compare here. I'll see that I output an appropriate warning, but it is tricky since e.g. g_object_ref and G_OBJECT_REF should not be confused.
One days later I found this: https://git.gnome.org/browse/gtk-doc/commit/?id=a90bc60eb1438f59dec8d7b0fc9e01629b4c4300 Please retest. There is still some delta though. Investigating further. One more thing that is weird, you can not calling gtkdoc-scangobj and therefore your docs don't expose any gobject related features (hierarchy, signals, properties, ...).
I have finished my investigation. Please re-test. * on the html, the delta is mostly that fixxref now properly build paths. Before it was missing path-separators * on the xml files a see a bit of delta, sometimes it is added details.
FYI, I would like to cut a release tonight.
I've been gone for two weeks, that's why the delay from my side. I tested with 1.26 release and it looks fine, feel free to close this bug. There are marked most/all E_IS_something_CLASS standard GObject macros an unused, but that's no big deal. The issue from the very top is fixed now. (In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #25) > One more thing that is weird, you can not calling gtkdoc-scangobj and > therefore your docs don't expose any gobject related features (hierarchy, > signals, properties, ...). Right, I'm partly aware of it, but I didn't mind yet. Maybe I'll reconsider, to get "the best experience" for developers reading the documentation.