Debian Codegraph @

HACKING

raw
1 Old website
2 ===========
3
4 See: https://gitlab.gnome.org/Infrastructure/gtk-web (in the git history)
5
6 The `gtk-doc/` directory has been removed after a big update to
7 [gtk.org](https://gtk.org/)
8
9 But it can contain useful information nevertheless, or a different wording at
10 presenting GTK-Doc.
11
12 Testing
13 =======
14
15 jhbuild --no-interact build 2>&1 | tee build.log
16 grep "gtkdoc-* line" build.log
17
18 jhbuild buildone --no-net glib
19
20 Since 1.23 we do have a snapshot feature to check the stability of the generated
21 xml/html. Simply run "make snapshot" under tests. Then make changes and run
22 "make check". The tests/sanity.sh will check for delta. If you want to inspect
23 what delta a change created, you can git checkout a revision before the change,
24 "make snapshot", go back to head and "make check", the sanity.sh test will now
25 fail and show the delta.
26
27 Releasing
28 =========
29
30 Version numbers and release dates are also present in:
31 `help/manual/C/index.docbook`
32
33 Optimizing & Measuring
34 ======================
35
36 cd tests/gobject/docs/html
37 time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "tester" --stringparam gtkdoc.version "1.12" ../../../../gtk-doc.xsl ../tester-docs.xml
38 ~ 1.1 sec.
39 time saxon ../tester-docs.xml ../../../../gtk-doc.xsl gtkdoc.bookname="tester" gtkdoc.version="1.12"
40 ~ 53 sec.
41 time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "tester" --stringparam gtkdoc.version "1.12" /usr/share/yelp-xsl/xslt/docbook/html/db2html.xsl ../tester-docs.xml
42 ~ 0.7 sec
43
44 cd /your/project/docs/html
45 time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "foo" --stringparam gtkdoc.version "1.12" /usr/share/gtk-doc/data/gtk-doc.xsl ../buzztrax-core-docs.xml
46 real 0m6.633s user 0m6.464s sys 0m0.128s
47 real 0m6.459s user 0m6.384s sys 0m0.068s
48
49 time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "buzztrax-core" --stringparam gtkdoc.version "1.12" /usr/share/yelp-xsl/xslt/docbook/html/db2html.xsl ../buzztrax-core-docs.xml
50 real 0m3.312s user 0m3.224s sys 0m0.076s
51 real 0m3.549s user 0m3.464s sys 0m0.076s
52
53
54 xsltproc --profile data.xsl data.xml 2>report.txt
55 cat report.txt | gprof2dot.py -e 0.01 -n 0.01 | dot -Tpng -o report.png
56
57 one can now use "GTKDOC_PROFILE=1 make" to run this during gtkdoc-mkhtml. It
58 still needs a change in gprof2dot.py
59 https://bugzilla.gnome.org/show_bug.cgi?id=612186#c3
60
61 Performance tips:
62 * uses keys when we have slow xpath selects
63 http://www.xml.com/pub/a/2002/02/06/key-lookups.html
64
65 Troubles with parsing regexps
66 =============================
67 Test regexps online:
68 http://www.solmetra.com/scripts/regex/index.php
69
70 Test Coverage
71 =============
72 sudo apt-get install python3-coverage
73 PYTHONPATH=$PWD python3-coverage run tests/scan.py
74 python3-coverage html --include="gtkdoc/*.py"
75
76 or
77
78 cd test; make coverage
79
80 Find Dead Code
81 ==============
82 sudo pip3 install vulture
83 PYTHONPATH=$PWD vulture gtkdoc/*.py gtkdoc-*.in