├── .gitignore ├── AUTHORS ├── COPYING ├── COPYING-DOCS ├── ChangeLog ├── HACKING ├── Makefile.am ├── NEWS ├── README ├── attic └── TODO ├── autogen.sh ├── build └── .gitignore ├── buildsystems ├── autotools │ ├── Makefile.am │ ├── gtk-doc.m4 │ ├── gtk-doc.make │ ├── gtk-doc.no-xslt.make │ ├── gtkdocize.in │ └── meson.build └── cmake │ ├── GtkDocConfig.cmake │ ├── GtkDocConfigVersion.cmake.in │ ├── GtkDocScanGObjWrapper.cmake │ ├── Makefile.am │ └── meson.build ├── configure.ac ├── devhelp2.xsd ├── devhelp2.xsl ├── doc ├── README ├── authors.txt ├── design-1.x.txt ├── design-2.x.txt ├── gnome.txt ├── gtkdoc.dot ├── sections-file.txt ├── setting-up.txt └── style-guide.txt ├── examples ├── Makefile.am └── README ├── git.mk ├── gtk-doc-fo.xsl ├── gtk-doc.doap ├── gtk-doc.pc.in ├── gtk-doc.xsl ├── gtkdoc-check.in ├── gtkdoc-depscan.in ├── gtkdoc-fixxref.in ├── gtkdoc-mkdb.in ├── gtkdoc-mkhtml.in ├── gtkdoc-mkhtml2.in ├── gtkdoc-mkman.in ├── gtkdoc-mkpdf.in ├── gtkdoc-rebase.in ├── gtkdoc-scan.in ├── gtkdoc-scangobj.in ├── gtkdoc ├── __init__.py ├── check.py ├── common.py ├── config.py ├── config_data.py.in ├── fixxref.py ├── highlight.py ├── md_to_db.py ├── meson.build ├── mkdb.py ├── mkhtml.py ├── mkhtml2.py ├── mkman.py ├── mkpdf.py ├── rebase.py ├── scan.py └── scangobj.py ├── gtkdoc_uninstalled.py.in ├── help ├── Makefile.am ├── manual │ ├── C │ │ ├── fdl-appendix.xml │ │ └── index.docbook │ ├── LINGUAS │ ├── Makefile.am │ ├── bn_IN │ │ └── bn_IN.po │ ├── cs │ │ └── cs.po │ ├── de │ │ └── de.po │ ├── el │ │ └── el.po │ ├── en_GB │ │ └── en_GB.po │ ├── es │ │ └── es.po │ ├── eu │ │ └── eu.po │ ├── fr │ │ └── fr.po │ ├── gl │ │ └── gl.po │ ├── gu │ │ └── gu.po │ ├── hu │ │ └── hu.po │ ├── meson.build │ ├── pt_BR │ │ └── pt_BR.po │ ├── sl │ │ └── sl.po │ ├── sv │ │ └── sv.po │ ├── ta │ │ └── ta.po │ ├── te │ │ └── te.po │ └── zh_CN │ │ └── zh_CN.po └── meson.build ├── m4 ├── ax_python_module.m4 ├── gtkdoc_jh_check_xml_catalog.m4 └── gtkdoc_jh_path_xml_catalog.m4 ├── meson.build ├── meson_options.txt ├── requirements.txt ├── style ├── COPYING ├── home.png ├── left-insensitive.png ├── left.png ├── meson.build ├── right-insensitive.png ├── right.png ├── style.css ├── up-insensitive.png └── up.png ├── tests ├── Makefile.am ├── annotations.sh ├── annotations │ ├── Makefile.am │ ├── docs │ │ ├── Makefile.am │ │ ├── meson.build │ │ ├── tester-docs.xml │ │ ├── tester-sections.txt │ │ └── xml │ │ │ └── meson.build │ ├── meson.build │ └── src │ │ ├── Makefile.am │ │ ├── tester.c │ │ └── tester.h ├── bugs.sh ├── bugs │ ├── Makefile.am │ ├── docs │ │ ├── Makefile.am │ │ ├── meson.build │ │ ├── tester-docs.xml │ │ ├── tester-sections.txt │ │ └── xml │ │ │ └── meson.build │ ├── meson.build │ └── src │ │ ├── Makefile.am │ │ ├── tester.c │ │ └── tester.h ├── check.py ├── common.py ├── empty.sh ├── empty │ ├── Makefile.am │ ├── docs │ │ ├── Makefile.am │ │ ├── meson.build │ │ └── xml │ │ │ └── meson.build │ ├── meson.build │ └── src │ │ ├── Makefile.am │ │ ├── tester.c │ │ └── tester.h ├── fail.sh ├── fail │ ├── Makefile.am │ ├── docs │ │ ├── Makefile.am │ │ ├── meson.build │ │ ├── tester-docs.xml │ │ ├── tester-sections.txt │ │ └── xml │ │ │ └── meson.build │ ├── meson.build │ └── src │ │ ├── Makefile.am │ │ ├── tester.c │ │ └── tester.h ├── gobject.sh ├── gobject │ ├── Makefile.am │ ├── docs │ │ ├── Makefile.am │ │ ├── images │ │ │ ├── meson.build │ │ │ └── object.png │ │ ├── meson.build │ │ ├── tester-docs.xml │ │ ├── tester-sections.txt │ │ └── xml │ │ │ └── meson.build │ ├── examples │ │ └── gobject.c │ ├── meson.build │ └── src │ │ ├── Makefile.am │ │ ├── giface.c │ │ ├── giface.h │ │ ├── gobject.c │ │ ├── gobject.h │ │ ├── gtypes.c │ │ ├── gtypes.h │ │ └── meson.build ├── gtk-doc.make ├── gtkdocentities.ent.in ├── gtkdoctest.sh ├── helpers │ ├── gtkdoc_check_runner.py │ ├── gtkdoc_fixxref_runner.py │ ├── gtkdoc_mkdb_runner.py │ ├── gtkdoc_mkhtml_runner.py │ ├── gtkdoc_scan_runner.py │ ├── gtkdoc_scangobj_runner.py │ └── meson.build ├── highlight.py ├── meson.build ├── mk_to_db.py ├── mkdb.py ├── mkhtml2.py ├── program.sh ├── program │ ├── Makefile.am │ ├── docs │ │ ├── Makefile.am │ │ ├── meson.build │ │ ├── tester-docs.xml │ │ ├── tester-sections.txt │ │ └── xml │ │ │ └── meson.build │ ├── meson.build │ └── src │ │ ├── Makefile.am │ │ └── test-program.c ├── repro │ ├── Makefile.am │ ├── docs │ │ ├── Makefile.am │ │ ├── meson.build │ │ └── tester-docs.xml │ ├── meson.build │ └── src │ │ ├── Makefile.am │ │ ├── tester.c │ │ └── tester.h ├── sanity.sh ├── scan.py └── tools.sh.in ├── tools ├── c10e-html.py ├── db2md.py ├── docpercentages.pl ├── git-pre-commit └── gtk-doc.el └── version-greater-or-equal.xsl /.gitignore: -------------------------------------------------------------------------------- 1 | __pycache__/ 2 | -------------------------------------------------------------------------------- /AUTHORS: -------------------------------------------------------------------------------- 1 | Damon Chaplin 2 | Owen Taylor 3 | 4 | -------------------------------------------------------------------------------- /ChangeLog: -------------------------------------------------------------------------------- 1 | See the 'NEWS' file or the version control system's log. 2 | -------------------------------------------------------------------------------- /HACKING: -------------------------------------------------------------------------------- 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 | General: https://wiki.gnome.org/MaintainersCorner/Releasing 31 | 32 | Specific to GTK-Doc 33 | ------------------- 34 | 35 | - Version numbers and release dates are also present in: 36 | `help/manual/C/index.docbook` 37 | 38 | Some commands: 39 | ``` 40 | TAR_OPTIONS="--owner=root --group=root" make distcheck 41 | ``` 42 | 43 | Optimizing & Measuring 44 | ====================== 45 | 46 | cd tests/gobject/docs/html 47 | time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "tester" --stringparam gtkdoc.version "1.12" ../../../../gtk-doc.xsl ../tester-docs.xml 48 | ~ 1.1 sec. 49 | time saxon ../tester-docs.xml ../../../../gtk-doc.xsl gtkdoc.bookname="tester" gtkdoc.version="1.12" 50 | ~ 53 sec. 51 | 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 52 | ~ 0.7 sec 53 | 54 | cd /your/project/docs/html 55 | 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 56 | real 0m6.633s user 0m6.464s sys 0m0.128s 57 | real 0m6.459s user 0m6.384s sys 0m0.068s 58 | 59 | 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 60 | real 0m3.312s user 0m3.224s sys 0m0.076s 61 | real 0m3.549s user 0m3.464s sys 0m0.076s 62 | 63 | 64 | xsltproc --profile data.xsl data.xml 2>report.txt 65 | cat report.txt | gprof2dot.py -e 0.01 -n 0.01 | dot -Tpng -o report.png 66 | 67 | one can now use "GTKDOC_PROFILE=1 make" to run this during gtkdoc-mkhtml. It 68 | still needs a change in gprof2dot.py 69 | https://bugzilla.gnome.org/show_bug.cgi?id=612186#c3 70 | 71 | Performance tips: 72 | * uses keys when we have slow xpath selects 73 | http://www.xml.com/pub/a/2002/02/06/key-lookups.html 74 | 75 | Troubles with parsing regexps 76 | ============================= 77 | Test regexps online: 78 | http://www.solmetra.com/scripts/regex/index.php 79 | 80 | Test Coverage 81 | ============= 82 | sudo apt-get install python3-coverage 83 | PYTHONPATH=$PWD python3-coverage run tests/scan.py 84 | python3-coverage html --include="gtkdoc/*.py" 85 | 86 | or 87 | 88 | cd test; make coverage 89 | 90 | Find Dead Code 91 | ============== 92 | sudo pip3 install vulture 93 | PYTHONPATH=$PWD vulture gtkdoc/*.py gtkdoc-*.in 94 | -------------------------------------------------------------------------------- /Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | ACLOCAL_AMFLAGS=-I m4 ${ACLOCAL_FLAGS} 3 | 4 | SUBDIRS = buildsystems/autotools buildsystems/cmake help tests 5 | 6 | bin_SCRIPTS = \ 7 | gtkdoc-check \ 8 | gtkdoc-depscan \ 9 | gtkdoc-fixxref \ 10 | gtkdoc-mkdb \ 11 | gtkdoc-mkhtml \ 12 | gtkdoc-mkhtml2 \ 13 | gtkdoc-mkman \ 14 | gtkdoc-mkpdf \ 15 | gtkdoc-rebase \ 16 | gtkdoc-scan \ 17 | gtkdoc-scangobj 18 | 19 | gtkdocdatadir = $(datadir)/gtk-doc/data 20 | gtkdocdata_DATA = \ 21 | gtk-doc.xsl \ 22 | version-greater-or-equal.xsl \ 23 | devhelp2.xsd \ 24 | devhelp2.xsl \ 25 | style/home.png \ 26 | style/left.png \ 27 | style/left-insensitive.png \ 28 | style/right.png \ 29 | style/right-insensitive.png \ 30 | style/up.png \ 31 | style/up-insensitive.png \ 32 | style/style.css 33 | 34 | pylibdatadir = $(datadir)/gtk-doc/python/gtkdoc 35 | pylibdata_DATA = \ 36 | gtkdoc/__init__.py \ 37 | gtkdoc/check.py \ 38 | gtkdoc/common.py \ 39 | gtkdoc/config.py \ 40 | gtkdoc/config_data.py \ 41 | gtkdoc/fixxref.py \ 42 | gtkdoc/highlight.py \ 43 | gtkdoc/md_to_db.py \ 44 | gtkdoc/mkdb.py \ 45 | gtkdoc/mkhtml.py \ 46 | gtkdoc/mkhtml2.py \ 47 | gtkdoc/mkman.py \ 48 | gtkdoc/mkpdf.py \ 49 | gtkdoc/rebase.py \ 50 | gtkdoc/scan.py \ 51 | gtkdoc/scangobj.py 52 | 53 | pkgconfigdir = $(datadir)/pkgconfig 54 | pkgconfig_DATA = gtk-doc.pc 55 | 56 | EXTRA_DIST = \ 57 | $(gtkdocdata_DATA) \ 58 | $(pylibdata_DATA) \ 59 | autogen.sh \ 60 | gtk-doc.pc.in \ 61 | gtk-doc.doap \ 62 | gtk-doc-fo.xsl \ 63 | meson.build \ 64 | meson_options.txt \ 65 | requirements.txt \ 66 | doc/README \ 67 | doc/authors.txt \ 68 | doc/gnome.txt \ 69 | doc/sections-file.txt \ 70 | doc/setting-up.txt \ 71 | doc/style-guide.txt \ 72 | examples/README \ 73 | examples/Makefile.am \ 74 | gtkdoc/meson.build \ 75 | gtkdoc_uninstalled.py.in \ 76 | style/COPYING \ 77 | style/meson.build \ 78 | tools/c10e-html.py \ 79 | tools/db2md.py \ 80 | tools/docpercentages.pl \ 81 | tools/gtk-doc.el \ 82 | COPYING-DOCS 83 | 84 | CLEANFILES = \ 85 | gtkdoc-checkc \ 86 | gtkdoc-depscanc \ 87 | gtkdoc-fixxrefc \ 88 | gtkdoc-mkdbc \ 89 | gtkdoc-mkhtmlc \ 90 | gtkdoc-mkhtml2c \ 91 | gtkdoc-mkmanc \ 92 | gtkdoc-mkpdfc \ 93 | gtkdoc-rebasec \ 94 | gtkdoc-scangobjc \ 95 | gtkdoc/__init__.pyc \ 96 | gtkdoc/check.pyc \ 97 | gtkdoc/common.pyc \ 98 | gtkdoc/config.pyc \ 99 | gtkdoc/fixxref.pyc \ 100 | gtkdoc/md_to_db.pyc \ 101 | gtkdoc/mkdb.pyc \ 102 | gtkdoc/mkhtml.pyc \ 103 | gtkdoc/mkhtml2.pyc \ 104 | gtkdoc/mkman.pyc \ 105 | gtkdoc/mkpdf.pyc \ 106 | gtkdoc/rebase.pyc \ 107 | gtkdoc/scan.pyc \ 108 | gtkdoc/scangobj.pyc 109 | 110 | DISTCLEANFILES = \ 111 | gtkdoc-check \ 112 | gtkdoc-depscan \ 113 | gtkdoc-fixxref \ 114 | gtkdocize \ 115 | gtkdoc-mkdb \ 116 | gtkdoc-mkhtml \ 117 | gtkdoc-mkhtml2 \ 118 | gtkdoc-mkman \ 119 | gtkdoc-mkpdf \ 120 | gtk-doc.pc \ 121 | gtkdoc-rebase \ 122 | gtkdoc-scangobj \ 123 | gtkdoc-scan \ 124 | gtkdoc/config.py 125 | 126 | MAINTAINERCLEANFILES = \ 127 | $(GITIGNORE_MAINTAINERCLEANFILES_TOPLEVEL) \ 128 | $(GITIGNORE_MAINTAINERCLEANFILES_MAKEFILE_IN) \ 129 | $(GITIGNORE_MAINTAINERCLEANFILES_M4_LIBTOOL) \ 130 | INSTALL \ 131 | RELNOTES.txt \ 132 | gtk-doc-*.tar.xz \ 133 | build-aux 134 | 135 | clean-local: 136 | -find . -name "__pycache__" -type d -exec rm -r "{}" \; 137 | 138 | ## We get warnings for left-over files when doing 'make distcheck' 139 | distuninstallcheck_listfiles = find . -type f -print 140 | 141 | # Workaround for automake 1.61 142 | # https://lists.gnu.org/archive/html/bug-automake/2018-04/msg00002.html 143 | distuninstallcheck_listfiles += | grep -v '__pycache__' 144 | 145 | -include $(top_srcdir)/git.mk 146 | -------------------------------------------------------------------------------- /README: -------------------------------------------------------------------------------- 1 | GTK-Doc - Documentation generator for C code 2 | ============================================ 3 | 4 | Development and maintenance status (December 2023) 5 | -------------------------------------------------- 6 | 7 | The GTK-Doc project is looking for additional co-maintainers, volunteers for 8 | reviewing merge requests and releasing new versions. 9 | 10 | The project is currently under-maintained, doesn't receive funding support and 11 | thus relies on voluntary work. 12 | 13 | That being said, GTK-Doc is still there and can still be used successfully. Some 14 | people still like (and prefer) the GTK-Doc output, combined with the Devhelp API 15 | browser. 16 | 17 | Comments welcome at: https://gitlab.gnome.org/GNOME/gtk-doc/-/issues/151 18 | 19 | Important message 20 | ----------------- 21 | 22 | To generate the `api-index-*.html` files, you need to use docbook-style-xsl 23 | version 1.79.1, not the latest version. 24 | 25 | See: 26 | - https://sourceforge.net/p/docbook/bugs/1401/ 27 | - https://gitlab.gnome.org/GNOME/gtk-doc/-/issues/36 28 | 29 | Introduction 30 | ------------ 31 | 32 | GTK-Doc is used to document C code. It is typically used to document the public 33 | API of libraries, such as GLib-based libraries, but it can also be used to 34 | document application code. 35 | 36 | Note that GTK-Doc wasn't originally intended to be a general-purpose 37 | documentation tool, so it can be a bit awkward to setup and use. 38 | For a more general-purpose documentation tool you may want to look at 39 | Doxygen (http://www.doxygen.org/). However GTK-Doc has some special code to 40 | document the signals and properties of GTK widgets and GObject classes which 41 | other tools may not have. 42 | 43 | From your source code comments GTK-Doc generates a DocBook XML document, which 44 | is then transformed into HTML and/or PDF. 45 | The generated HTML documentation can be browsed in an ordinary web browser or 46 | by using the special Devhelp API browser 47 | (see https://wiki.gnome.org/Apps/Devhelp). 48 | 49 | Requirements 50 | ------------ 51 | 52 | Python 3.x 53 | http:///www.python.org 54 | 55 | Additional python modules: 56 | For the tests: unittest, parameterized 57 | For mkhtml2 (experimental): anytree, lxml and pygments 58 | For fixxref: pygments 59 | 60 | For XML output (recommended): 61 | 62 | The DocBook XML DTD. 63 | http://www.oasis-open.org/docbook/ 64 | 65 | The DocBook XSL Stylesheets. 66 | http://docbook.sourceforge.net/projects/xsl/ 67 | 68 | libxslt & libxml2 >= 2.3.6. 69 | http://xmlsoft.org/ 70 | 71 | For PDF output: 72 | 73 | the dblatex tool. 74 | http://dblatex.sourceforge.net/ 75 | 76 | Most distributions now have packages for all of these, so I would strongly 77 | advise that you grab those. 78 | 79 | See the documentation in the help/manual/ directory for more information. You 80 | can read it for example with yelp: `yelp help/manual/C/index.docbook`. 81 | 82 | Building 83 | -------- 84 | 85 | We are supporting two build systems to build gtk-doc for some transitions time. 86 | 87 | ### Build using the Autotools 88 | 89 | In order to build with the classic Autotools system use these commands: 90 | 91 | Build from git: 92 | ./autogen.sh; make 93 | 94 | Build from dist tarball: 95 | ./configure; make 96 | 97 | There are a few parameters one can pass to ./configure, run ./configure --help 98 | to see them. Also ./autogen.sh can take those settings (and will hand them 99 | through to ./configure). 100 | 101 | To run the tests: 102 | make check 103 | 104 | To install: 105 | make install 106 | 107 | To make a release: 108 | make distcheck 109 | or 110 | make dist 111 | 112 | ### Build using Meson 113 | 114 | Support for Meson is new. 115 | 116 | Build it from git: 117 | meson build . 118 | ninja -C build 119 | 120 | There are some options one can specify too: 121 | meson build . --prefix= 122 | meson build . -Dautotools_support=false 123 | meson build . -Dcmake_support=false 124 | meson build . -Dyelp_manual=false 125 | 126 | To run tests: 127 | ninja -C build test 128 | 129 | To install: 130 | ninja -C build install 131 | 132 | To make a release: 133 | ninja -C build dist 134 | -------------------------------------------------------------------------------- /autogen.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | # Run this to generate all the initial makefiles, etc. 3 | 4 | test -n "$srcdir" || srcdir=`dirname "$0"` 5 | test -n "$srcdir" || srcdir=. 6 | 7 | olddir=`pwd` 8 | cd "$srcdir" 9 | 10 | AUTORECONF=`which autoreconf` 11 | if test -z $AUTORECONF; then 12 | echo "*** No autoreconf found, please install it ***" 13 | exit 1 14 | else 15 | autoreconf --force --install --verbose || exit $? 16 | fi 17 | 18 | cd "$olddir" 19 | test -n "$NOCONFIGURE" || "$srcdir/configure" "$@" 20 | -------------------------------------------------------------------------------- /build/.gitignore: -------------------------------------------------------------------------------- 1 | * 2 | -------------------------------------------------------------------------------- /buildsystems/autotools/Makefile.am: -------------------------------------------------------------------------------- 1 | EXTRA_DIST = \ 2 | $(autotoolsdata_DATA) \ 3 | gtk-doc.m4 \ 4 | meson.build 5 | 6 | CLEANFILES = gtk-doc.flat.make gtk-doc.no-xslt-flat.make 7 | 8 | bin_SCRIPTS = gtkdocize 9 | 10 | autotoolsdatadir = $(datadir)/gtk-doc/data 11 | autotoolsdata_DATA = \ 12 | gtk-doc.make \ 13 | gtk-doc.flat.make \ 14 | gtk-doc.no-xslt.make \ 15 | gtk-doc.no-xslt-flat.make 16 | 17 | aclocaldir = $(datadir)/aclocal 18 | aclocal_DATA = gtk-doc.m4 19 | 20 | gtk-doc.flat.make: gtk-doc.make 21 | @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@ 22 | 23 | gtk-doc.no-xslt-flat.make: gtk-doc.no-xslt.make 24 | @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@ 25 | 26 | -include $(top_srcdir)/git.mk 27 | -------------------------------------------------------------------------------- /buildsystems/autotools/meson.build: -------------------------------------------------------------------------------- 1 | configure_file( 2 | input: 'gtkdocize.in', 3 | output: 'gtkdocize', 4 | configuration: binary_in, 5 | install: true, 6 | install_dir: get_option('bindir'), 7 | ) 8 | 9 | foreach mode : ['', 'no-xslt'] 10 | if mode == '' 11 | nested = '' 12 | flat = '.flat' 13 | else 14 | nested = '.' + mode 15 | flat = nested + '-flat' 16 | endif 17 | 18 | custom_target( 19 | 'gtk-doc' + flat + '.make', 20 | input: 'gtk-doc' + nested + '.make', 21 | output: 'gtk-doc' + flat + '.make', 22 | install: true, 23 | install_dir: pkgdatadir, 24 | capture: true, 25 | command: [ 26 | 'sed', 27 | '-e', 28 | 's/EXTRA_DIST =/EXTRA_DIST +=/', 29 | '@INPUT@', 30 | ] 31 | ) 32 | 33 | install_data( 34 | ['gtk-doc' + nested + '.make'], 35 | install_dir: pkgdatadir, 36 | ) 37 | endforeach 38 | 39 | custom_target( 40 | 'gtk-doc.m4', 41 | input: 'gtk-doc.m4', 42 | output: 'gtk-doc.m4', 43 | install: true, 44 | install_dir: get_option('datadir') / 'aclocal', 45 | command: [ 46 | 'cp', 47 | '-f', 48 | '@INPUT@', 49 | '@OUTPUT@', 50 | ], 51 | ) 52 | -------------------------------------------------------------------------------- /buildsystems/cmake/GtkDocConfigVersion.cmake.in: -------------------------------------------------------------------------------- 1 | # CMake package version configuration file for GTK-Doc. 2 | 3 | set(PACKAGE_VERSION @PACKAGE_VERSION@) 4 | 5 | # Check whether the requested PACKAGE_FIND_VERSION is compatible 6 | if("${PACKAGE_VERSION}" VERSION_LESS "${PACKAGE_FIND_VERSION}") 7 | set(PACKAGE_VERSION_COMPATIBLE FALSE) 8 | else() 9 | set(PACKAGE_VERSION_COMPATIBLE TRUE) 10 | if ("${PACKAGE_VERSION}" VERSION_EQUAL "${PACKAGE_FIND_VERSION}") 11 | set(PACKAGE_VERSION_EXACT TRUE) 12 | endif() 13 | endif() 14 | -------------------------------------------------------------------------------- /buildsystems/cmake/GtkDocScanGObjWrapper.cmake: -------------------------------------------------------------------------------- 1 | # Internal -- for use with UseGtkDoc.cmake 2 | # 3 | #============================================================================= 4 | # Copyright 2009 Rich Wareham 5 | # Copyright 2015 Lautsprecher Teufel GmbH 6 | # 7 | # This program is free software; you can redistribute it and/or modify 8 | # it under the terms of the GNU General Public License as published by 9 | # the Free Software Foundation; either version 2 of the License, or 10 | # (at your option) any later version. 11 | # 12 | # This program is distributed in the hope that it will be useful, 13 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 | # GNU General Public License for more details. 16 | # 17 | # You should have received a copy of the GNU General Public License 18 | # along with this program. If not, see . 19 | #============================================================================= 20 | 21 | # This is needed for find_package(PkgConfig) to work correctly -- 22 | # CMAKE_MINIMUM_REQUIRED_VERSION needs to be defined. 23 | cmake_minimum_required(VERSION 3.2) 24 | 25 | if(NOT APPLE) 26 | # We use pkg-config to find glib et al 27 | find_package(PkgConfig) 28 | # Find glib et al 29 | pkg_check_modules(GLIB REQUIRED glib-2.0 gobject-2.0) 30 | 31 | foreach(_flag ${EXTRA_CFLAGS} ${GLIB_CFLAGS}) 32 | set(ENV{CFLAGS} "$ENV{CFLAGS} '${_flag}'") 33 | endforeach(_flag) 34 | 35 | foreach(_flag ${EXTRA_LDFLAGS} ${GLIB_LDFLAGS}) 36 | set(ENV{LDFLAGS} "$ENV{LDFLAGS} '${_flag}'") 37 | endforeach(_flag) 38 | 39 | foreach(_flag ${EXTRA_LDPATH}) 40 | if(DEFINED ENV{LD_LIBRARY_PATH}) 41 | set(ENV{LD_LIBRARY_PATH} "$ENV{LD_LIBRARY_PATH}:${_flag}") 42 | else(DEFINED ENV{LD_LIBRARY_PATH}) 43 | set(ENV{LD_LIBRARY_PATH} "${_flag}") 44 | endif(DEFINED ENV{LD_LIBRARY_PATH}) 45 | endforeach(_flag) 46 | 47 | message(STATUS "Executing gtkdoc-scangobj with:") 48 | message(STATUS " CFLAGS: $ENV{CFLAGS}") 49 | message(STATUS " LDFLAGS: $ENV{LDFLAGS}") 50 | message(STATUS " LDPATH: $ENV{LD_LIBRARY_PATH}") 51 | 52 | execute_process(COMMAND ${GTKDOC_SCANGOBJ_EXE} 53 | "--module=${doc_prefix}" 54 | "--types=${output_types}" 55 | "--output-dir=${output_dir}" 56 | ${_scanobjopts} 57 | WORKING_DIRECTORY "${output_dir}" 58 | RESULT_VARIABLE _scan_result) 59 | 60 | if(_scan_result EQUAL 0) 61 | message(STATUS "Scan succeeded.") 62 | else(_scan_result EQUAL 0) 63 | message(SEND_ERROR "Scan failed.") 64 | endif(_scan_result EQUAL 0) 65 | 66 | endif(NOT APPLE) 67 | 68 | # vim:sw=4:ts=4:et:autoindent 69 | -------------------------------------------------------------------------------- /buildsystems/cmake/Makefile.am: -------------------------------------------------------------------------------- 1 | EXTRA_DIST = \ 2 | GtkDocConfig.cmake \ 3 | GtkDocConfigVersion.cmake.in \ 4 | GtkDocScanGObjWrapper.cmake \ 5 | meson.build 6 | 7 | CLEANFILES = \ 8 | GtkDocConfigVersion.cmake 9 | 10 | cmakedir = $(datadir)/cmake/GtkDoc 11 | cmake_DATA = \ 12 | GtkDocConfig.cmake \ 13 | GtkDocConfigVersion.cmake \ 14 | GtkDocScanGObjWrapper.cmake 15 | 16 | -include $(top_srcdir)/git.mk 17 | -------------------------------------------------------------------------------- /buildsystems/cmake/meson.build: -------------------------------------------------------------------------------- 1 | cmake_in = configuration_data() 2 | cmake_in.set('PACKAGE_VERSION', meson.project_version()) 3 | 4 | configure_file( 5 | input: 'GtkDocConfigVersion.cmake.in', 6 | output: 'GtkDocConfigVersion.cmake', 7 | configuration: cmake_in, 8 | install: true, 9 | install_dir: get_option('libdir') / 'cmake' / 'GtkDoc', 10 | ) 11 | 12 | gtkdoc_cmake_data = [ 13 | 'GtkDocConfig.cmake', 14 | 'GtkDocScanGObjWrapper.cmake', 15 | ] 16 | 17 | install_data( 18 | gtkdoc_cmake_data, 19 | install_dir: get_option('libdir') / 'cmake' / 'GtkDoc', 20 | ) 21 | -------------------------------------------------------------------------------- /doc/README: -------------------------------------------------------------------------------- 1 | Note 2 | ==== 3 | 4 | There is now a user manual which can be read using yelp and can be found under 5 | 'development'. Please refer to this documentation for up-to-date information. 6 | 7 | 8 | Files 9 | ===== 10 | 11 | setting-up.txt 12 | 5-step guide to setting up a module to use gtk-doc. 13 | 14 | gnome.txt 15 | information on the source code comments format which the Gnome project 16 | has just started to use. 17 | 18 | sections-file.txt 19 | describes the MODULE-sections.txt file which is used to organise the 20 | documentation. 21 | 22 | style-guide.txt 23 | Initial draft of a style guide for writing GTK+ docs. 24 | 25 | authors.txt 26 | notes for authors of the GTK documentation. The abbreviations to use, 27 | a few useful DocBook tags etc. 28 | -------------------------------------------------------------------------------- /doc/authors.txt: -------------------------------------------------------------------------------- 1 | Note 2 | ==== 3 | 4 | There is now a user manual which can be read using yelp and can be found under 5 | 'development'. Please refer to this documentation for up-to-date information. 6 | 7 | 8 | General 9 | ======= 10 | 11 | The files to edit manually are generated in the tmpl/ directory. 12 | Remember to use < or > instead of '<' and '>', in these files. 13 | 14 | The first part of each function/macro/struct etc. description should be 15 | a very short summary of what it is. This may be used at some point to 16 | produce a short reference guide which can be printed out. 17 | 18 | For macros which return a value just like a function, you must manually 19 | add a '@Returns: ' field. 20 | 21 | You may want to rearrange the functions/macros etc. to split them into 22 | related sections. To do this rearrange the MODULE-sections.txt 23 | files. You can also add between functions. Currently this just 24 | results in a blank line between them in the synopsis. 25 | 26 | If a function or macro has a very long description, you may want the table 27 | of parameters to go somewhere in the middle rather than after the description 28 | as would normally happen. To place the table of parameters in the middle of 29 | the description simple write "" on its own line at the 30 | desired location. 31 | 32 | 33 | Abbreviations 34 | ============= 35 | 36 | These are expanded into appropriate DocBook tags, saving a lot of typing. 37 | I've used the Gnome ones (see gnome.txt) but also added '#'. 38 | 39 | Use function() to refer to functions or macros which take arguments. 40 | 41 | Use @param to refer to parameters. (I've also used this when referring to 42 | parameters of other functions, related to the one being described.) 43 | 44 | Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS. 45 | 46 | Use #symbol to refer to other types of symbol, e.g. structs and enums 47 | and macros which don't take arguments. 48 | 49 | 50 | 51 | Useful DocBook Tags 52 | =================== 53 | 54 | These are the DocBook tags which I have used or I think could be useful. 55 | Let me know if I'm doing something wrong! 56 | 57 | 58 | To link to another section in the GTK docs: 59 | 60 | Hash Tables 61 | 62 | The linkend is the SGML id on the top item of the page you want to link to. 63 | For most pages this is currently the part ("gtk", "gdk", glib") and then 64 | the page title ("Hash Tables"). For widgets it is just the class name. 65 | Spaces and underscores are converted to '-' to conform to SGML. 66 | 67 | 68 | To refer to an external function, e.g. a standard C function: 69 | 70 | ... 71 | 72 | 73 | To include example code: 74 | 75 | 76 | Using a GHashTable. 77 | 78 | ... 79 | 80 | 81 | 82 | or possibly this, for very short code fragments which don't need a title: 83 | 84 | 85 | 86 | ... 87 | 88 | 89 | 90 | 91 | To include bulleted lists: 92 | 93 | 94 | 95 | 96 | 97 | ... 98 | 99 | 100 | 101 | 102 | 103 | ... 104 | 105 | 106 | 107 | 108 | 109 | 110 | To include a note which stands out from the text: 111 | 112 | 113 | 114 | Make sure you free the data after use. 115 | 116 | 117 | 118 | To refer to a type: 119 | 120 | unsigned char 121 | 122 | 123 | To refer to an external structure (not one described in the GTK docs): 124 | 125 | XFontStruct 126 | 127 | 128 | To refer to a field of a structure: 129 | 130 | len 131 | 132 | 133 | To refer to a class name, we could possibly use: 134 | 135 | GtkWidget 136 | 137 | but you'll probably be using #GtkWidget instead (to automatically create 138 | a link to the GtkWidget page - see the abbreviations above). 139 | 140 | 141 | To emphasize text: 142 | 143 | This is important 144 | 145 | but I haven't been using it so far. 146 | 147 | 148 | For filenames use: 149 | 150 | c:\windows 151 | 152 | -------------------------------------------------------------------------------- /doc/design-1.x.txt: -------------------------------------------------------------------------------- 1 | = gtk-doc-1.X = 2 | This document attempts to reverse engineer some design decisions in 3 | gtk-doc-1.X. 4 | 5 | == sgml-ids == 6 | When creating SGML IDS, we append ":CAPS" to all 7 | all-caps identifiers to prevent name clashes (SGML ids are case-insensitive). 8 | (It basically never is the case that mixed-case identifiers would collide.) 9 | 10 | Unfortunately we create ambiguous ids. The document structure ids are e.g. 11 | GtkWidget.{top_of_page,synopsis,object-hierarchy,...} 12 | and that is ambiguous with eventual structure member of the same name. 13 | 14 | cd tests 15 | find . -name "*.xml" -exec grep -o "id=\"[a-zA-Z_:.\-]*\"" {} \; | sort | uniq 16 | 17 | == section-ids == 18 | gtk-doc differentiates between plain-sections and gobject-sections: 19 | +---------+----------------+ 20 | | type | section-id | 21 | +---------+----------------+ 22 | | plain | $module-$title | 23 | | gobject | $title | 24 | +---------+----------------+ 25 | 26 | - links to #GtkWidget would go to $title 27 | - linking to the struct would need #GtkWidget-struct 28 | 29 | -------------------------------------------------------------------------------- /doc/gnome.txt: -------------------------------------------------------------------------------- 1 | Note 2 | ==== 3 | 4 | There is now a user manual which can be read using yelp and can be found under 5 | 'development'. Please refer to this documentation for up-to-date information. 6 | 7 | 8 | HowTo 9 | ===== 10 | 11 | These are the comment blocks used in Gnome source files to document 12 | functions (and macros, signals and properties, if you want). 13 | 14 | /** 15 | * function_name: 16 | * @par1: description of parameter 1. These can extend over more than 17 | * one line. 18 | * @par2: description of parameter 2 19 | * 20 | * The function description goes here. You can use @par1 to refer to parameters 21 | * so that they are highlighted in the output. You can also use %constant 22 | * for constants, function_name2() for functions and #GtkWidget for links to 23 | * other declarations (which may be documented elsewhere). 24 | * 25 | * Returns: an integer. 26 | */ 27 | 28 | The block starts with '/**'. 29 | Each line starts with ' * '. 30 | 31 | The second line is the function name, optionally followed by a ':'. In 32 | order to document signals in inline comments, use a name of the form 33 | class::signal, e.g. GtkWidget::notify-child. For properties, use a 34 | name of the form class:property, e.g. GtkAlignment:top-padding. Note 35 | that gtk-doc expects the signal and property names to be spelled with 36 | hyphens, not underlines. 37 | 38 | Following the function name are the parameters, e.g. '@par1:' above. 39 | 40 | A blank line MUST be used to separate parameter descriptions from the main 41 | description (otherwise it is assumed to be a continuation of the parameter 42 | description.) 43 | 44 | After the main description is a 'Returns:' line to describe the 45 | returned value of the function (if it is not void). 46 | 47 | Text inside the descriptions can use these special characters (they 48 | will be expanded into appropriate DocBook tags): 49 | 50 | @name a parameter. 51 | %name a constant. 52 | name() reference to a function, or a macro which works like a function 53 | (this will be turned into a hypertext link if the function is 54 | documented anywhere). 55 | #name reference to any other type of declaration, e.g. a struct, enum, 56 | union, or macro (this will also be turned into a link if possible). 57 | 58 | To avoid problems, the characters '<', '>' and '&' in the descriptions are 59 | converted into the SGML entities < > and &. 60 | This means that you can't use Docbook SGML tags, unless specify the --sgml-mode 61 | option for gtkdoc-mkdb, which suppresses the escaping of '<', '>' and 62 | '&' and allows Docbook markup in inline comments. 63 | 64 | If you are using markup in inline comments, you must be careful to to 65 | not run into problems with the automatic splitting of the comment in 66 | paragraphs at empty lines. A line counts as empty for this purpose, if 67 | it is empty after the removal of the initial ' * ' prefix. Thus you 68 | can work around this problem by adding some trailing whitespace to 69 | lines which should appear as empty, but not end a paragraph. This is 70 | especially relevant in code examples, which often contain empty lines. 71 | 72 | Some more hints regarding examples: Hyperlinks in the formatted examples 73 | are confusing, therefore you should suppress the gtk-doc markup by using 74 | function() instead of function(). Use character entities to refer 75 | to the characters %, &, < or #, e.g. 76 | 77 | if (a < b && verbose) 78 | printf ("bla %s %#x", bla, a); 79 | 80 | would become 81 | 82 | if (a < b && verbose) 83 | printf ("bla %s %#x", bla, a); 84 | 85 | -------------------------------------------------------------------------------- /doc/gtkdoc.dot: -------------------------------------------------------------------------------- 1 | /* files and tools in gtk-doc workflow 2 | * dot -Tpng gtkdoc.dot -ogtkdoc.png 3 | */ 4 | 5 | digraph gtkdoc { 6 | /* graph attributes */ 7 | /*rankdir=BT;*/ 8 | 9 | /* default node attributes */ 10 | node [ shape=box]; 11 | 12 | /* tools nodes */ 13 | gtkdoc_scan [label="gtkdoc-scan",shape="ellipse" ]; 14 | gtkdoc_scangobj [label="gtkdoc-scangobj",shape="ellipse" ]; 15 | gtkdoc_mkdb [label="gtkdoc-mkdb",shape="ellipse" ]; 16 | gtkdoc_mkhtml [label="gtkdoc-mkhtml",shape="ellipse" ]; 17 | gtkdoc_fixxref [label="gtkdoc-fixxref",shape="ellipse" ]; 18 | gtkdoc_rebase [label="gtkdoc-rebase",shape="ellipse" ]; 19 | gtkdoc_check [label="gtkdoc-check",shape="ellipse" ]; 20 | 21 | /* file nodes */ 22 | headers [label="headers\nall headers under DOC_SOURCE_DIR\n+EXTRA_HFILES\n-IGNORE_HFILES"]; 23 | sources [label="source code\nall files under DOC_SOURCE_DIR\nmatching SUFFIXES or *.{c,h}"]; 24 | binary [label="compiled binary"]; 25 | xml [label="docbook xml"]; 26 | html [label="html"]; 27 | module_decl_list [label="*-decl-list.txt" ]; 28 | module_decl [label="*-decl.txt" ]; 29 | module_types [label="*.types" ]; 30 | module_sections [label="*-section.txt" ]; 31 | module_signals [label="*.signals" ]; 32 | module_hierarchy [label="*.hierarchy" ]; 33 | module_interfaces [label="*.interfaces" ]; 34 | module_prerequisites [label="*.prerequisites" ]; 35 | module_args [label="*.args" ]; 36 | module_undeclared [label="*-undeclared.txt" ]; 37 | module_undocumented [label="*-undocumented.txt" ]; 38 | module_unused [label="*-unused.txt" ]; 39 | 40 | /* tool invocation */ 41 | gtkdoc_scan -> gtkdoc_scangobj -> gtkdoc_mkdb -> gtkdoc_mkhtml -> gtkdoc_fixxref -> gtkdoc_rebase -> gtkdoc_check [style="dotted"]; 42 | 43 | /* file usage */ 44 | headers -> gtkdoc_scan; 45 | gtkdoc_scan -> module_sections [label="--rebuild-sections", style="dashed"]; 46 | gtkdoc_scan -> module_types [label="--rebuild-types", style="dashed"]; 47 | gtkdoc_scan -> module_decl; 48 | gtkdoc_scan -> module_decl_list; 49 | 50 | binary -> gtkdoc_scangobj; 51 | module_types -> gtkdoc_scangobj; 52 | gtkdoc_scangobj -> module_signals; 53 | gtkdoc_scangobj -> module_hierarchy; 54 | gtkdoc_scangobj -> module_interfaces; 55 | gtkdoc_scangobj -> module_prerequisites; 56 | gtkdoc_scangobj -> module_args; 57 | 58 | sources -> gtkdoc_mkdb; 59 | module_sections -> gtkdoc_mkdb; 60 | module_decl -> gtkdoc_mkdb; 61 | module_signals -> gtkdoc_mkdb; 62 | module_args -> gtkdoc_mkdb; 63 | module_hierarchy -> gtkdoc_mkdb; 64 | module_interfaces -> gtkdoc_mkdb; 65 | module_prerequisites -> gtkdoc_mkdb; 66 | gtkdoc_mkdb -> xml; 67 | gtkdoc_mkdb -> module_undeclared; 68 | gtkdoc_mkdb -> module_undocumented; 69 | gtkdoc_mkdb -> module_unused; 70 | 71 | xml -> gtkdoc_mkhtml -> html; 72 | 73 | html -> gtkdoc_fixxref -> html; 74 | html -> gtkdoc_rebase -> html; 75 | 76 | module_undeclared -> gtkdoc_check; 77 | module_undocumented -> gtkdoc_check; 78 | module_unused -> gtkdoc_check; 79 | } 80 | 81 | -------------------------------------------------------------------------------- /doc/sections-file.txt: -------------------------------------------------------------------------------- 1 | Note 2 | ==== 3 | 4 | There is now a user manual which can be read using yelp and can be found under 5 | 'development'. Please refer to this documentation for up-to-date information. 6 | 7 | 8 | *-section.txt 9 | ============= 10 | 11 | This describes the MODULE-sections.txt file which is used to organise the 12 | documentation output by gtk-doc. 13 | 14 | The file is divided into sections. Each section will be output to a separate 15 | file in the templates, which also corresponds to a SGML file, and a file in 16 | the final HTML files. Each section contains a list of function/macro etc. 17 | names, which can be rearranged into the desired order. 18 | 19 | The ... tag is used to specify the file name, without any 20 | suffix. For example, using 'gnome-config' will result in the 21 | section declarations being output in the template file tmpl/gnome-config.sgml, 22 | which will be converted into the DocBook SGML file sgml/gnome-config.sgml. 23 | (The name of the html file is based on the module name and the section title, 24 | or for widgets it is based on the widget name converted to lower case). 25 | 26 | The ... tag is used to specify the title of the section. 27 | It is only useful before the templates are initially created, since the title 28 | set in the template file overrides this. 29 | 30 | You can group items in the section by using the tag. Currently 31 | it outputs a blank line between subsections in the synopsis section. 32 | You can also use for standard GtkObject declarations 33 | (e.g. the functions like gtk_object_get_type and macros like GTK_OBJECT(), 34 | GTK_IS_OBJECT() etc.) Currently these are left out of the documentation. 35 | You can also use for private declarations which will not 36 | be output (Its a handy way to avoid warning messages about unused 37 | declarations.). If your library contains private types which you don't want 38 | to appear in the object hierarchy and the list of implemented or required 39 | interfaces, add them to a Private subsection. 40 | 41 | You can also use ... to specify the #include files which 42 | are shown in the synopsis sections. It contains a comma-separate list of 43 | #include files, without the angle brackets. If you set it outside of any 44 | sections, it acts for all sections until the end of the file. If you set it 45 | within a section, it only applies to that section. 46 | 47 | If a line starts with a '#' it is treated as a comment and ignored. 48 | 49 | Example MODULE-sections.txt file: 50 | 51 | # This is a comment. 52 | gnome.h 53 | 54 |
55 | gnome-dateedit 56 | GnomeDateEdit 57 | gnome_date_edit_new 58 | gnome_date_edit_set_time 59 | gnome_date_edit_set_popup_range 60 | gnome_date_edit_get_date 61 | 62 | GNOME_DATE_EDIT 63 | GNOME_IS_DATE_EDIT 64 | gnome_date_edit_get_type 65 | GNOME_DATE_EDIT_CLASS 66 |
67 | -------------------------------------------------------------------------------- /doc/setting-up.txt: -------------------------------------------------------------------------------- 1 | Note 2 | ==== 3 | 4 | There is now a user manual which can be read using yelp and can be found under 5 | 'development'. Please refer to this documentation for up-to-date information. 6 | 7 | 8 | How to Set Up an Application or Library to use GTK-Doc 9 | ====================================================== 10 | 11 | This assumes that you are using autoconf & automake to build your package, 12 | and already have gtk-doc installed properly. 13 | 14 | 15 | 1. Add this line to your autogen.sh, before the calls to autoheader, automake 16 | or autoconf: 17 | 18 | gtkdocize || exit 1 19 | 20 | If you are using gnome-autogen.sh it already runs gtkdocize for you. 21 | If you don't have an autogen.sh script you may need to run gtkdocize 22 | manually. (All gtkdocize does is copy gtk-doc.make to your project.) 23 | 24 | 25 | 2. Add this line to your configure.in (somewhere before the call to AC_OUTPUT) 26 | 27 | GTK_DOC_CHECK(1.0) 28 | 29 | The number in brackets is the minimum version of gtk-doc required. 30 | 31 | 32 | 3. Create a directory in your project where you want the docs to be built, 33 | e.g. 'myproject/docs/reference'. If you want to create several separate 34 | pieces of documentation you can create subdirectories for each one here. 35 | (e.g. GTK+ has subdirectories for gtk, gdk and gdk-pixbuf.) 36 | 37 | 38 | 4. Copy examples/Makefile.am to this directory (or subdirectories) and edit 39 | the variables at the top of the file. (See the GTK+ source for an example.) 40 | 41 | 42 | 5. Add the new Makefile(s) to your configure.in's AC_OUTPUT call, and make sure 43 | all the SUBDIRS variables are set properly so the docs directory is built. 44 | 45 | 46 | 6. If your library or application includes GtkObjects/GObjects, and you want 47 | their signals, arguments/parameters and position in the hierarchy to be 48 | documented: 49 | 50 | Create a MODULE.types file in the docs directory, e.g. "myproject.types". 51 | This should contain any '#include' directives needed to compile a program 52 | with your module, and a list of functions to initialize all of the widgets 53 | and objects in the library. For example, the gtk.types file starts like 54 | this: 55 | 56 | #include 57 | 58 | gtk_accel_label_get_type 59 | gtk_adjustment_get_type 60 | gtk_alignment_get_type 61 | gtk_arrow_get_type 62 | 63 | ============================================================================= 64 | 65 | That's it! If you now build the application or library you should get a 66 | complete set of documentation. gtk-doc is normally off by default so you 67 | may have to pass '--enable-gtk-doc' to autogen.sh or configure.in. 68 | 69 | (Note that due to a problem with make the build may fail the very first time 70 | it is run, but if you run make again it should work. It only fails because 71 | there are no files in the tmpl/ directory initially. As soon as these are 72 | created it works fine.) 73 | 74 | 75 | You can tweak the output in several ways: 76 | 77 | o modify the main SGML file to add introductory sections or to split the 78 | documentation into several chapters. 79 | 80 | o modify the MODULE-sections.txt file to rearrange the documentation into 81 | different sections or a different order (see sections-file.txt for info). 82 | 83 | o add a MODULE-overrides.txt to override particular declarations. 84 | 85 | 86 | Damon 87 | -------------------------------------------------------------------------------- /examples/Makefile.am: -------------------------------------------------------------------------------- 1 | # -*- mode: makefile -*- 2 | # 3 | # Makefile.am - template makefile for gtk-doc module 4 | # Copyright (C) 2007-2017 Stefan Sauer 5 | # 6 | # This program is free software: you can redistribute it and/or modify 7 | # it under the terms of the GNU General Public License as published by 8 | # the Free Software Foundation, either version 3 of the License, or 9 | # (at your option) any later version. 10 | # 11 | # This program is distributed in the hope that it will be useful, 12 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 13 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 | # GNU General Public License for more details. 15 | # 16 | # You should have received a copy of the GNU General Public License 17 | # along with this program. If not, see . 18 | # 19 | # As a special exception, the above copyright owner gives unlimited 20 | # permission to copy, distribute and modify this Makefile.am template. 21 | # You need not follow the terms of the GNU General Public License when 22 | # using or distributing such Makefile.am files, even though portions of 23 | # the text of the Makefile.am appear in them. The GNU General Public 24 | # License (GPL) does govern all other use of the material that constitutes 25 | # the Makefile.am template. 26 | 27 | # This is a blank Makefile.am for using gtk-doc. 28 | # Copy this to your project's API docs directory and modify the variables to 29 | # suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples 30 | # of using the various options. 31 | 32 | # The name of the module, e.g. 'glib'. 33 | DOC_MODULE= 34 | 35 | # Uncomment for versioned docs and specify the version of the module, e.g. '2'. 36 | #DOC_MODULE_VERSION=2 37 | 38 | # The top-level XML file. 39 | DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml 40 | 41 | # Directories containing the source code. 42 | # gtk-doc will search all .c and .h files beneath these paths 43 | # for inline comments documenting functions and macros. 44 | # e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk 45 | DOC_SOURCE_DIR= 46 | 47 | # Extra options to pass to gtkdoc-scangobj. Normally not needed. 48 | SCANGOBJ_OPTIONS= 49 | 50 | # Extra options to supply to gtkdoc-scan. 51 | # e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" 52 | SCAN_OPTIONS= 53 | 54 | # Extra options to supply to gtkdoc-mkdb 55 | # e.g. MKDB_OPTIONS=--xml-mode --output-format=xml 56 | MKDB_OPTIONS=--xml-mode --output-format=xml 57 | 58 | # Extra options to supply to gtkdoc-mkhtml 59 | MKHTML_OPTIONS= 60 | 61 | # Extra options to supply to gtkdoc-fixref. Normally not needed. 62 | # e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html 63 | FIXXREF_OPTIONS= 64 | 65 | # Used for dependencies. The docs will be rebuilt if any of these change. 66 | # e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h 67 | # e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c 68 | HFILE_GLOB= 69 | CFILE_GLOB= 70 | 71 | # Extra header to include when scanning, which are not under DOC_SOURCE_DIR 72 | # e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h 73 | EXTRA_HFILES= 74 | 75 | # Header files or dirs to ignore when scanning. Use base file/dir names 76 | # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code 77 | IGNORE_HFILES= 78 | 79 | # Images to copy into HTML directory. 80 | # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png 81 | HTML_IMAGES= 82 | 83 | # Extra files that are included by $(DOC_MAIN_SGML_FILE). 84 | # e.g. content_files=running.xml building.xml changes-2.0.xml 85 | content_files= 86 | 87 | # Files where gtk-doc abbreviations (#GtkWidget) are expanded 88 | # e.g. expand_content_files=running.xml 89 | expand_content_files= 90 | 91 | # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. 92 | # Only needed if you are using gtkdoc-scangobj to dynamically query widget 93 | # signals and properties. 94 | # e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) 95 | # e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) 96 | GTKDOC_CFLAGS= 97 | GTKDOC_LIBS= 98 | 99 | # This includes the standard gtk-doc make rules, copied by gtkdocize. 100 | include $(top_srcdir)/gtk-doc.make 101 | 102 | # Comment this out if you don't want 'make check' to test you doc status 103 | # and run some sanity checks 104 | if ENABLE_GTK_DOC 105 | TESTS_ENVIRONMENT = \ 106 | DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ 107 | SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir) 108 | TESTS = $(GTKDOC_CHECK) 109 | endif 110 | 111 | -include $(top_srcdir)/git.mk 112 | -------------------------------------------------------------------------------- /examples/README: -------------------------------------------------------------------------------- 1 | 2 | The Makefile.am here should be copied to your project's API documentation 3 | directory, and the variables edited appropriately. 4 | 5 | See doc/setting-up.txt for documentation on setting up a project to use 6 | gtk-doc. 7 | 8 | See the GTK+ and libglade sources for example Makefile.am option settings. 9 | 10 | -------------------------------------------------------------------------------- /gtk-doc-fo.xsl: -------------------------------------------------------------------------------- 1 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 7pt 12 | always 13 | 14 | 15 | 16 | 17 | 18 | #D0D0D0 19 | 0.5pt 20 | solid 21 | #575757 22 | 3pt 23 | 24 | 25 | 26 | 27 | 28 | blue 29 | inherit 30 | 31 | 32 | 33 | 34 | 35 | 36 | -------------------------------------------------------------------------------- /gtk-doc.doap: -------------------------------------------------------------------------------- 1 | 2 | 7 | gtk-doc 8 | Documentation generator for C code 9 | 10 | GTK-Doc is used to document C code. It is typically used to document the public 11 | API of libraries, such as GLib-based libraries, but it can also be used to 12 | document application code. 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | Python 21 | 22 | 23 | 24 | 25 | Sébastien Wilmet 26 | 27 | swilmet 28 | 29 | 30 | 31 | 32 | 33 | 34 | Matthias Clasen 35 | 36 | matthiasc 37 | 38 | 39 | 40 | 41 | 50 | 51 | -------------------------------------------------------------------------------- /gtk-doc.pc.in: -------------------------------------------------------------------------------- 1 | prefix=@prefix@ 2 | exec_prefix=@exec_prefix@ 3 | data_dir=@datadir@/@PACKAGE@/data 4 | 5 | Name: gtk-doc 6 | Description: API documentation generator 7 | Version: @VERSION@ 8 | -------------------------------------------------------------------------------- /gtkdoc-check.in: -------------------------------------------------------------------------------- 1 | #!@PYTHON@ 2 | # -*- python; coding: utf-8 -*- 3 | # 4 | # gtk-doc - GTK DocBook documentation generator. 5 | # Copyright (C) 2007 David Nečas 6 | # 2007-2017 Stefan Sauer 7 | # 8 | # This program is free software; you can redistribute it and/or modify 9 | # it under the terms of the GNU General Public License as published by 10 | # the Free Software Foundation; either version 2 of the License, or 11 | # (at your option) any later version. 12 | # 13 | # This program is distributed in the hope that it will be useful, 14 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 15 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 | # GNU General Public License for more details. 17 | # 18 | # You should have received a copy of the GNU General Public License 19 | # along with this program; if not, write to the Free Software 20 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 21 | # 22 | 23 | import argparse 24 | import sys 25 | 26 | try: 27 | import gtkdoc_uninstalled 28 | except ModuleNotFoundError: 29 | sys.path.append('@PYTHON_PACKAGE_DIR@') 30 | 31 | from gtkdoc import common, check, config 32 | 33 | if __name__ == '__main__': 34 | parser = argparse.ArgumentParser( 35 | description='gtkdoc-check version %s - run documentation unit tests' % config.version) 36 | parser.add_argument('--version', action='version', version=config.version) 37 | options = parser.parse_args() 38 | 39 | common.setup_logging() 40 | 41 | sys.exit(check.run(options)) 42 | -------------------------------------------------------------------------------- /gtkdoc-fixxref.in: -------------------------------------------------------------------------------- 1 | #!@PYTHON@ 2 | # -*- python -*- 3 | # 4 | # gtk-doc - GTK DocBook documentation generator. 5 | # Copyright (C) 1998 Damon Chaplin 6 | # 2007-2016 Stefan Sauer 7 | # 8 | # This program is free software; you can redistribute it and/or modify 9 | # it under the terms of the GNU General Public License as published by 10 | # the Free Software Foundation; either version 2 of the License, or 11 | # (at your option) any later version. 12 | # 13 | # This program is distributed in the hope that it will be useful, 14 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 15 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 | # GNU General Public License for more details. 17 | # 18 | # You should have received a copy of the GNU General Public License 19 | # along with this program; if not, write to the Free Software 20 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 21 | # 22 | 23 | import argparse 24 | import os 25 | import sys 26 | 27 | try: 28 | import gtkdoc_uninstalled 29 | except ModuleNotFoundError: 30 | sys.path.append('@PYTHON_PACKAGE_DIR@') 31 | 32 | from gtkdoc import common, config, fixxref 33 | 34 | 35 | if __name__ == '__main__': 36 | parser = argparse.ArgumentParser( 37 | description='gtkdoc-fixxref version %s - fix cross references in html files' % config.version) 38 | parser.add_argument('--version', action='version', version=config.version) 39 | parser.add_argument('--module', required=True, 40 | help='Name of the doc module being processed.') 41 | parser.add_argument('--module-dir', default='', 42 | help='The directory which contains the generated HTML.') 43 | parser.add_argument('--html-dir', default='', 44 | help='The directory where gtk-doc generated documentation is ' 45 | 'installed.') 46 | parser.add_argument('--extra-dir', default=[], action='append', 47 | help='Directories to recursively scan for indices (*.devhelp2) ' 48 | 'in addition to HTML_DIR') 49 | parser.add_argument('--src-lang', default='c', 50 | help='Programing language used for syntax highlighting. ' 51 | 'The available languages depend on the source ' 52 | 'highlighter you use.') 53 | 54 | options = parser.parse_args() 55 | 56 | if not options.module_dir: 57 | options.module_dir = os.path.join(options.html_dir, options.module) 58 | 59 | common.setup_logging() 60 | 61 | fixxref.Run(options) 62 | -------------------------------------------------------------------------------- /gtkdoc-mkdb.in: -------------------------------------------------------------------------------- 1 | #!@PYTHON@ 2 | # -*- python; coding: utf-8 -*- 3 | # 4 | # gtk-doc - GTK DocBook documentation generator. 5 | # Copyright (C) 1998 Damon Chaplin 6 | # 2007-2016 Stefan Sauer 7 | # 8 | # This program is free software; you can redistribute it and/or modify 9 | # it under the terms of the GNU General Public License as published by 10 | # the Free Software Foundation; either version 2 of the License, or 11 | # (at your option) any later version. 12 | # 13 | # This program is distributed in the hope that it will be useful, 14 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 15 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 | # GNU General Public License for more details. 17 | # 18 | # You should have received a copy of the GNU General Public License 19 | # along with this program; if not, write to the Free Software 20 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 21 | # 22 | 23 | from __future__ import print_function 24 | 25 | import argparse 26 | import sys 27 | 28 | try: 29 | import gtkdoc_uninstalled 30 | except ModuleNotFoundError: 31 | sys.path.append('@PYTHON_PACKAGE_DIR@') 32 | 33 | from gtkdoc import common, config, mkdb 34 | 35 | if __name__ == '__main__': 36 | parser = argparse.ArgumentParser() 37 | parser.add_argument('--version', action='version', version=config.version) 38 | parser.add_argument('--module', required=True, 39 | help='Name of the doc module being parsed') 40 | parser.add_argument('--source-dir', action='append', dest='source_dir', default=[]) 41 | parser.add_argument('--source-suffixes', dest='source_suffixes', default='') 42 | parser.add_argument('--ignore-files', dest='ignore_files', default='') 43 | parser.add_argument('--output-dir', dest='output_dir', default='') 44 | parser.add_argument('--tmpl-dir', dest='tmpl_dir', help="DEPRECATED") 45 | parser.add_argument('--main-sgml-file', dest='main_sgml_file', default='') 46 | parser.add_argument('--expand-content-files', dest='expand_content_files', default='') 47 | group = parser.add_mutually_exclusive_group() 48 | group.add_argument('--sgml-mode', action='store_true', default=False, dest='sgml_mode') 49 | group.add_argument('--xml-mode', action='store_true', default=False, dest='xml_mode') 50 | parser.add_argument('--default-stability', dest='default_stability', 51 | choices=['', 'Stable', 'Private', 'Unstable'], default='') 52 | parser.add_argument('--default-includes', dest='default_includes', default='') 53 | parser.add_argument('--output-format', default='xml') # MUST be 'xml', deprecate? 54 | parser.add_argument('--name-space', dest='name_space', default='') 55 | parser.add_argument('--outputallsymbols', default=False, action='store_true') 56 | parser.add_argument('--outputsymbolswithoutsince', default=False, action='store_true') 57 | 58 | options = parser.parse_args() 59 | 60 | if options.output_format != "xml": 61 | sys.exit('Invalid format "%s" passed to --output.format' % options.output_format) 62 | 63 | common.setup_logging() 64 | 65 | mkdb.Run(options) 66 | -------------------------------------------------------------------------------- /gtkdoc-mkhtml.in: -------------------------------------------------------------------------------- 1 | #!@PYTHON@ 2 | # -*- python; coding: utf-8 -*- 3 | # 4 | # gtk-doc - GTK DocBook documentation generator. 5 | # Copyright (C) 1998 Owen Taylor 6 | # 2001-2005 Damon Chaplin 7 | # 2009-2017 Stefan Sauer 8 | # 2017 Jussi Pakkanen 9 | # 10 | # This program is free software; you can redistribute it and/or modify 11 | # it under the terms of the GNU General Public License as published by 12 | # the Free Software Foundation; either version 2 of the License, or 13 | # (at your option) any later version. 14 | # 15 | # This program is distributed in the hope that it will be useful, 16 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 17 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 | # GNU General Public License for more details. 19 | # 20 | # You should have received a copy of the GNU General Public License 21 | # along with this program; if not, write to the Free Software 22 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 23 | # 24 | 25 | import argparse 26 | import sys 27 | 28 | try: 29 | import gtkdoc_uninstalled 30 | except ModuleNotFoundError: 31 | sys.path.append('@PYTHON_PACKAGE_DIR@') 32 | 33 | from gtkdoc import common, config, mkhtml 34 | 35 | if __name__ == '__main__': 36 | parser = argparse.ArgumentParser( 37 | description='gtkdoc-mkhtml version %s - generate documentation in html format' % config.version) 38 | parser.add_argument('--version', action='version', version=config.version) 39 | parser.add_argument('--verbose', default=False, action='store_true', 40 | help='Print extra output while processing') 41 | parser.add_argument('--path', default=[], action='append', 42 | help='Extra source directories') 43 | parser.add_argument('args', nargs='*', 44 | help='MODULE DRIVER_FILE') 45 | # TODO: only for testing, replace with env-var 46 | parser.add_argument('--uninstalled', action='store_true', default=False, 47 | help='???') 48 | 49 | options = parser.parse_args() 50 | if len(options.args) < 2: 51 | sys.exit('Too few arguments') 52 | 53 | common.setup_logging() 54 | 55 | sys.exit(mkhtml.run(options)) 56 | -------------------------------------------------------------------------------- /gtkdoc-mkhtml2.in: -------------------------------------------------------------------------------- 1 | #!@PYTHON@ 2 | # -*- python; coding: utf-8 -*- 3 | # 4 | # gtk-doc - GTK DocBook documentation generator. 5 | # Copyright (C) 2018 Stefan Sauer 6 | # 7 | # This program is free software; you can redistribute it and/or modify 8 | # it under the terms of the GNU General Public License as published by 9 | # the Free Software Foundation; either version 2 of the License, or 10 | # (at your option) any later version. 11 | # 12 | # This program is distributed in the hope that it will be useful, 13 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 | # GNU General Public License for more details. 16 | # 17 | # You should have received a copy of the GNU General Public License 18 | # along with this program; if not, write to the Free Software 19 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 20 | # 21 | 22 | import argparse 23 | import sys 24 | 25 | try: 26 | import gtkdoc_uninstalled 27 | except ModuleNotFoundError: 28 | sys.path.append('@PYTHON_PACKAGE_DIR@') 29 | 30 | from gtkdoc import common, config, mkhtml2 31 | 32 | if __name__ == '__main__': 33 | parser = argparse.ArgumentParser( 34 | description='gtkdoc-mkhtml version %s - generate documentation in html format' % config.version) 35 | parser.add_argument('--version', action='version', version=config.version) 36 | parser.add_argument('--output-dir', default='.', 37 | help='The directory where the results are stored') 38 | parser.add_argument('--path', default=[], action='append', 39 | help='Extra source directories') 40 | parser.add_argument('--extra-dir', default=[], action='append', 41 | help='Directories to recursively scan for indices (*.devhelp2)' 42 | 'in addition to HTML_DIR') 43 | parser.add_argument('--src-lang', default='c', 44 | help='Programing language used for syntax highlighting. This' 45 | 'can be any language pygments supports.') 46 | parser.add_argument('args', nargs='*', 47 | help='MODULE DRIVER_FILE') 48 | # TODO: only for testing, replace with env-var 49 | parser.add_argument('--uninstalled', action='store_true', default=False, 50 | help='???') 51 | 52 | options = parser.parse_args() 53 | if len(options.args) != 2: 54 | sys.exit('Too few arguments') 55 | 56 | common.setup_logging() 57 | 58 | sys.exit(mkhtml2.run(options)) 59 | -------------------------------------------------------------------------------- /gtkdoc-mkman.in: -------------------------------------------------------------------------------- 1 | #!@PYTHON@ 2 | # -*- python; coding: utf-8 -*- 3 | # 4 | # gtk-doc - GTK DocBook documentation generator. 5 | # Copyright (C) 1998 Owen Taylor 6 | # 2001-2005 Damon Chaplin 7 | # 2009-2017 Stefan Sauer 8 | # 2017 Jussi Pakkanen 9 | # 10 | # This program is free software; you can redistribute it and/or modify 11 | # it under the terms of the GNU General Public License as published by 12 | # the Free Software Foundation; either version 2 of the License, or 13 | # (at your option) any later version. 14 | # 15 | # This program is distributed in the hope that it will be useful, 16 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 17 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 | # GNU General Public License for more details. 19 | # 20 | # You should have received a copy of the GNU General Public License 21 | # along with this program; if not, write to the Free Software 22 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 23 | # 24 | 25 | import argparse 26 | import sys 27 | 28 | try: 29 | import gtkdoc_uninstalled 30 | except ModuleNotFoundError: 31 | sys.path.append('@PYTHON_PACKAGE_DIR@') 32 | 33 | from gtkdoc import common, config, mkman 34 | 35 | if __name__ == '__main__': 36 | parser = argparse.ArgumentParser( 37 | description='gtkdoc-mkman version %s - generate documentation in man format' % config.version) 38 | parser.add_argument('--version', action='version', version=config.version) 39 | parser.add_argument('--verbose', default=False, action='store_true', 40 | help='Print extra output while processing') 41 | parser.add_argument('--path', default=[], action='append', 42 | help='Extra source directories') 43 | parser.add_argument('args', nargs=2, 44 | help='MODULE DRIVER_FILE') 45 | # TODO: only for testing, replace with env-var 46 | parser.add_argument('--uninstalled', action='store_true', default=False, 47 | help='???') 48 | 49 | options = parser.parse_args() 50 | 51 | common.setup_logging() 52 | 53 | sys.exit(mkman.run(options)) 54 | -------------------------------------------------------------------------------- /gtkdoc-mkpdf.in: -------------------------------------------------------------------------------- 1 | #!@PYTHON@ 2 | # -*- python; coding: utf-8 -*- 3 | # 4 | # gtk-doc - GTK DocBook documentation generator. 5 | # Copyright (C) 2009-2017 Stefan Sauer 6 | # 2017 Jussi Pakkanen 7 | # 8 | # This program is free software; you can redistribute it and/or modify 9 | # it under the terms of the GNU General Public License as published by 10 | # the Free Software Foundation; either version 2 of the License, or 11 | # (at your option) any later version. 12 | # 13 | # This program is distributed in the hope that it will be useful, 14 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 15 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 | # GNU General Public License for more details. 17 | # 18 | # You should have received a copy of the GNU General Public License 19 | # along with this program; if not, write to the Free Software 20 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 21 | # 22 | 23 | import argparse 24 | import sys 25 | 26 | try: 27 | import gtkdoc_uninstalled 28 | except ModuleNotFoundError: 29 | sys.path.append('@PYTHON_PACKAGE_DIR@') 30 | 31 | from gtkdoc import common, config, mkpdf 32 | 33 | if __name__ == '__main__': 34 | parser = argparse.ArgumentParser( 35 | description='gtkdoc-mkpdf version %s - generate documentation in pdf format' % config.version) 36 | parser.add_argument('--version', action='version', version=config.version) 37 | parser.add_argument('--verbose', default=False, action='store_true', 38 | help='Print extra output while processing.') 39 | parser.add_argument('--path', default=[], action='append', 40 | help='Extra source directories.') 41 | parser.add_argument('--imgdir', default=[], action='append', 42 | help='Extra image directories.') 43 | parser.add_argument('--uninstalled', action='store_true', default=False, 44 | help='???') 45 | parser.add_argument('args', nargs=2, 46 | help='MODULE DRIVER_FILE') 47 | 48 | options = parser.parse_args() 49 | 50 | common.setup_logging() 51 | 52 | sys.exit(mkpdf.run(options)) 53 | -------------------------------------------------------------------------------- /gtkdoc-rebase.in: -------------------------------------------------------------------------------- 1 | #!@PYTHON@ 2 | # -*- python -*- 3 | # 4 | # gtk-doc - GTK DocBook documentation generator. 5 | # Copyright (C) 1998 Damon Chaplin 6 | # 2007 David Necas (Yeti) 7 | # 2007-2016 Stefan Sauer 8 | # 9 | # This program is free software; you can redistribute it and/or modify 10 | # it under the terms of the GNU General Public License as published by 11 | # the Free Software Foundation; either version 2 of the License, or 12 | # (at your option) any later version. 13 | # 14 | # This program is distributed in the hope that it will be useful, 15 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 16 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 | # GNU General Public License for more details. 18 | # 19 | # You should have received a copy of the GNU General Public License 20 | # along with this program; if not, write to the Free Software 21 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 22 | # 23 | 24 | import argparse 25 | import sys 26 | 27 | try: 28 | import gtkdoc_uninstalled 29 | except ModuleNotFoundError: 30 | sys.path.append('@PYTHON_PACKAGE_DIR@') 31 | 32 | from gtkdoc import common, config, rebase 33 | 34 | 35 | if __name__ == '__main__': 36 | parser = argparse.ArgumentParser( 37 | description='gtkdoc-rebase version %s - rewrite links in html docs' % config.version) 38 | parser.add_argument('--version', action='version', version=config.version) 39 | parser.add_argument('--html-dir', required=True, 40 | help='The directory which contains the installed HTML') 41 | parser.add_argument('--other-dir', default=[], action='append', 42 | help='Directories to recursively scan for indices (*.devhelp2).' 43 | 'May be used more than once for multiple directories.') 44 | parser.add_argument('--dest-dir', default='', 45 | help='Staging area virtual root, this prefix will be removed' 46 | 'from HTML_DIR for relative link calculation.') 47 | parser.add_argument('--aggressive', action='store_true', default=False, 48 | help='Rebase links to all files that are under a directory matching a package name.') 49 | parser.add_argument('--verbose', action='store_true', default=False, 50 | help='Print extra output while processing') 51 | parser.add_argument('--online', action='store_true', default=False, 52 | help='Prefer cross-references to online documents') 53 | parser.add_argument('--relative', action='store_true', default=False, 54 | help='Prefer relative cross-references') 55 | 56 | options = parser.parse_args() 57 | 58 | common.setup_logging() 59 | 60 | sys.exit(rebase.run(options)) 61 | -------------------------------------------------------------------------------- /gtkdoc-scan.in: -------------------------------------------------------------------------------- 1 | #!@PYTHON@ 2 | # -*- python -*- 3 | # 4 | # gtk-doc - GTK DocBook documentation generator. 5 | # Copyright (C) 1998 Damon Chaplin 6 | # 2007-2016 Stefan Sauer 7 | # 8 | # This program is free software; you can redistribute it and/or modify 9 | # it under the terms of the GNU General Public License as published by 10 | # the Free Software Foundation; either version 2 of the License, or 11 | # (at your option) any later version. 12 | # 13 | # This program is distributed in the hope that it will be useful, 14 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 15 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 | # GNU General Public License for more details. 17 | # 18 | # You should have received a copy of the GNU General Public License 19 | # along with this program; if not, write to the Free Software 20 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 21 | # 22 | 23 | from __future__ import print_function 24 | 25 | import argparse 26 | import sys 27 | 28 | try: 29 | import gtkdoc_uninstalled 30 | except ModuleNotFoundError: 31 | sys.path.append('@PYTHON_PACKAGE_DIR@') 32 | 33 | from gtkdoc import common, config, scan 34 | 35 | if __name__ == '__main__': 36 | parser = argparse.ArgumentParser( 37 | description='gtkdoc-scan version %s - scan header files for public symbols' % config.version) 38 | parser.add_argument('--version', action='version', version=config.version) 39 | parser.add_argument('--module', required=True, 40 | help='Name of the doc module being processed.') 41 | parser.add_argument('--source-dir', action='append', default=[], 42 | help='Directories containing the source files to scan') 43 | parser.add_argument('--ignore-headers', default='', 44 | help='A space-separated list of header files/dirs not to scan') 45 | parser.add_argument('--output-dir', default='.', 46 | help='The directory where the results are stored') 47 | parser.add_argument('--deprecated-guards', default='does_not_match_any_cpp_symbols_at_all_nope', 48 | help='A |-separated list of symbols used as deprecation guards') 49 | parser.add_argument('--ignore-decorators', default='(?=no)match', 50 | help='A |-separated list of additional decorators in' 51 | 'declarations that should be ignored') 52 | parser.add_argument('--rebuild-sections', action='store_true', default=False, 53 | help='Rebuild (overwrite) the MODULE-sections.txt file') 54 | parser.add_argument('--rebuild-types', action='store_true', default=False, 55 | help='Automatically recreate the MODULE.types file using' 56 | 'all the *_get_type() functions found') 57 | parser.add_argument('headers', nargs='*') 58 | 59 | options = parser.parse_args() 60 | 61 | common.setup_logging() 62 | 63 | scan.Run(options) 64 | -------------------------------------------------------------------------------- /gtkdoc-scangobj.in: -------------------------------------------------------------------------------- 1 | #!@PYTHON@ 2 | # -*- python -*- 3 | # 4 | # gtk-doc - GTK DocBook documentation generator. 5 | # Copyright (C) 1998 Damon Chaplin 6 | # 2007-2016 Stefan Sauer 7 | # 8 | # This program is free software; you can redistribute it and/or modify 9 | # it under the terms of the GNU General Public License as published by 10 | # the Free Software Foundation; either version 2 of the License, or 11 | # (at your option) any later version. 12 | # 13 | # This program is distributed in the hope that it will be useful, 14 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 15 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 | # GNU General Public License for more details. 17 | # 18 | # You should have received a copy of the GNU General Public License 19 | # along with this program; if not, write to the Free Software 20 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 21 | # 22 | 23 | import argparse 24 | import os 25 | import sys 26 | 27 | try: 28 | import gtkdoc_uninstalled 29 | except ModuleNotFoundError: 30 | sys.path.append('@PYTHON_PACKAGE_DIR@') 31 | 32 | from gtkdoc import common, config, scangobj 33 | 34 | if __name__ == '__main__': 35 | parser = argparse.ArgumentParser( 36 | description='gtkdoc-rebase version %s - introspect g-objects' % config.version) 37 | parser.add_argument('--version', action='version', version=config.version) 38 | parser.add_argument('--module', required=True, 39 | help='Name of the doc module being parsed') 40 | parser.add_argument('--types', default='', 41 | help='The name of the file to store the types in') 42 | parser.add_argument('--type-init-func', default='', 43 | help='The init function(s) to call instead of g_type_init()') 44 | parser.add_argument('--query-child-properties', default='', 45 | help='A function that returns a list of child properties for a class') 46 | parser.add_argument('--output-dir', default='.', 47 | help='The directory where the results are stored') 48 | parser.add_argument('--cc', default='', help='The compiler to use') 49 | parser.add_argument('--ld', default='', help='The linker to use') 50 | parser.add_argument('--cflags', type=str, default=[], help='Compiler flags', 51 | action='append') 52 | parser.add_argument('--ldflags', type=str, default=[], help='Linker flags', 53 | action='append') 54 | parser.add_argument('--run', default='', 55 | help='Command for running the scanner') 56 | parser.add_argument('--verbose', action='store_true', default=False, 57 | help='Print extra output while processing') 58 | 59 | options = parser.parse_args() 60 | 61 | if options.types == '': 62 | options.types = os.path.join(options.output_dir, options.module + '.types') 63 | if options.cflags: 64 | options.cflags = ' '.join(options.cflags) 65 | if options.ldflags: 66 | options.ldflags = ' '.join(options.ldflags) 67 | 68 | if not options.cc: 69 | options.cc = os.environ.get('CC', 'gcc') 70 | if not options.ld: 71 | options.ld = os.environ.get('LD', options.cc) 72 | if not options.cflags: 73 | options.cflags = os.environ.get('CFLAGS', '') 74 | if not options.ldflags: 75 | options.ldflags = os.environ.get('LDFLAGS', '') 76 | if not options.run: 77 | options.run = os.environ.get('RUN', '') 78 | 79 | common.setup_logging() 80 | 81 | sys.exit(scangobj.run(options)) 82 | -------------------------------------------------------------------------------- /gtkdoc/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GNOME/gtk-doc/6fafd62a12a86b774c3a48c00ee2c7bda1459ce4/gtkdoc/__init__.py -------------------------------------------------------------------------------- /gtkdoc/config.py: -------------------------------------------------------------------------------- 1 | import os 2 | import sys 3 | 4 | try: 5 | from gtkdoc_uninstalled import builddir 6 | exec(open(os.path.join(builddir, 'gtkdoc', 'config_data.py')).read()) 7 | except ModuleNotFoundError: 8 | from gtkdoc.config_data import * 9 | 10 | 11 | def get_dirs(uninstalled): 12 | try: 13 | from gtkdoc_uninstalled import sourcedir 14 | gtkdocdir = sourcedir 15 | styledir = os.path.join(sourcedir, 'style') 16 | except ModuleNotFoundError: 17 | if uninstalled: 18 | # this does not work from buiddir!=srcdir 19 | gtkdocdir = os.path.split(sys.argv[0])[0] 20 | if not os.path.exists(gtkdocdir + '/gtk-doc.xsl'): 21 | # try 'srcdir' (set from makefiles) too 22 | if os.path.exists(os.environ.get("ABS_TOP_SRCDIR", '') + '/gtk-doc.xsl'): 23 | gtkdocdir = os.environ['ABS_TOP_SRCDIR'] 24 | styledir = gtkdocdir + '/style' 25 | else: 26 | gtkdocdir = os.path.join(datadir, 'gtk-doc/data') 27 | styledir = gtkdocdir 28 | return (gtkdocdir, styledir) 29 | -------------------------------------------------------------------------------- /gtkdoc/config_data.py.in: -------------------------------------------------------------------------------- 1 | version = "@VERSION@" 2 | 3 | # tools 4 | dblatex = '@DBLATEX@' 5 | fop = '@FOP@' 6 | pkg_config = '@PKG_CONFIG@' 7 | xsltproc = '@XSLTPROC@' 8 | 9 | # configured directories 10 | prefix = '@prefix@' 11 | datarootdir = "@datarootdir@".replace('${prefix}', prefix) 12 | datadir = "@datadir@".replace('${datarootdir}', datarootdir) 13 | 14 | exeext = '@EXEEXT@' 15 | -------------------------------------------------------------------------------- /gtkdoc/highlight.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | # -*- python; coding: utf-8 -*- 3 | # 4 | # gtk-doc - GTK DocBook documentation generator. 5 | # Copyright (C) 2018 Stefan Sauer 6 | # 7 | # This program is free software; you can redistribute it and/or modify 8 | # it under the terms of the GNU General Public License as published by 9 | # the Free Software Foundation; either version 2 of the License, or 10 | # (at your option) any later version. 11 | # 12 | # This program is distributed in the hope that it will be useful, 13 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 | # GNU General Public License for more details. 16 | # 17 | # You should have received a copy of the GNU General Public License 18 | # along with this program; if not, write to the Free Software 19 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 20 | # 21 | 22 | """ 23 | Highlight sourcecode snippets. 24 | """ 25 | import os 26 | 27 | from pygments import highlight 28 | from pygments.lexers import CLexer 29 | from pygments.lexers import get_lexer_by_name 30 | from pygments.formatters import HtmlFormatter 31 | 32 | # lazily constructed lexer cache 33 | LEXERS = { 34 | 'c': CLexer() 35 | } 36 | HTML_FORMATTER = HtmlFormatter(nowrap=True) 37 | 38 | 39 | def highlight_code(code, lang='c'): 40 | if lang not in LEXERS: 41 | LEXERS[lang] = get_lexer_by_name(lang) 42 | lexer = LEXERS.get(lang, None) 43 | if not lexer: 44 | return None 45 | return highlight(code, lexer, HTML_FORMATTER) 46 | 47 | 48 | def append_style_defs(css_file_name): 49 | os.chmod(css_file_name, 0o644) 50 | with open(css_file_name, 'at', newline='\n', encoding='utf-8') as css: 51 | css.write(HTML_FORMATTER.get_style_defs()) 52 | -------------------------------------------------------------------------------- /gtkdoc/meson.build: -------------------------------------------------------------------------------- 1 | config_py = configuration_data() 2 | config_py.set('prefix', get_option('prefix')) 3 | config_py.set('datarootdir', join_paths('${prefix}', get_option('datadir'))) 4 | config_py.set('datadir', '${datarootdir}') 5 | 6 | config_py.set('DBLATEX', dblatex_prg_path) 7 | config_py.set('FOP', fop_prg_path) 8 | config_py.set('PKG_CONFIG', pkgconfig_prg_path) 9 | config_py.set('XSLTPROC', xsltproc_prg_path) 10 | 11 | config_py.set('VERSION', meson.project_version()) 12 | config_py.set('EXEEXT', '') 13 | 14 | configure_file( 15 | input: 'config_data.py.in', 16 | output: 'config_data.py', 17 | configuration: config_py, 18 | install: true, 19 | install_dir: pkgpythondir / 'gtkdoc', 20 | ) 21 | 22 | gtkdoc_sources = [ 23 | '__init__.py', 24 | 'check.py', 25 | 'common.py', 26 | 'config.py', 27 | 'fixxref.py', 28 | 'highlight.py', 29 | 'md_to_db.py', 30 | 'mkdb.py', 31 | 'mkhtml.py', 32 | 'mkhtml2.py', 33 | 'mkman.py', 34 | 'mkpdf.py', 35 | 'rebase.py', 36 | 'scan.py', 37 | 'scangobj.py', 38 | ] 39 | 40 | install_data(gtkdoc_sources, 41 | install_dir: pkgpythondir / 'gtkdoc', 42 | ) 43 | -------------------------------------------------------------------------------- /gtkdoc/mkhtml.py: -------------------------------------------------------------------------------- 1 | # -*- python; coding: utf-8 -*- 2 | # 3 | # gtk-doc - GTK DocBook documentation generator. 4 | # Copyright (C) 1998 Owen Taylor 5 | # 2001-2005 Damon Chaplin 6 | # 2009-2017 Stefan Sauer 7 | # 2017 Jussi Pakkanen 8 | # 9 | # This program is free software; you can redistribute it and/or modify 10 | # it under the terms of the GNU General Public License as published by 11 | # the Free Software Foundation; either version 2 of the License, or 12 | # (at your option) any later version. 13 | # 14 | # This program is distributed in the hope that it will be useful, 15 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 16 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 | # GNU General Public License for more details. 18 | # 19 | # You should have received a copy of the GNU General Public License 20 | # along with this program; if not, write to the Free Software 21 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 22 | # 23 | 24 | import logging 25 | import os 26 | import sys 27 | import subprocess 28 | import shutil 29 | from glob import glob 30 | 31 | from . import config 32 | 33 | 34 | def run_xsltproc(options, args): 35 | command = [config.xsltproc] 36 | # we could do "$path_option $PWD " to avoid needing rewriting entities that 37 | # are copied from the header into docs under xml 38 | if os.environ.get("GTKDOC_PROFILE", '') == '': 39 | if len(options.path): 40 | command += ['--path', ':'.join(options.path)] 41 | logging.info('running "%s"', ' '.join(command + args)) 42 | return subprocess.call(command + args) 43 | else: 44 | command += ['--profile'] 45 | if len(options.path): 46 | command += ['--path', ':'.join(options.path)] 47 | logging.info('running "%s"', ' '.join(command + args)) 48 | return subprocess.call(command + args, stderr=open('profile.txt', 'w')) 49 | 50 | 51 | def run(options): 52 | logging.info('options: %s', str(options.__dict__)) 53 | 54 | module = options.args[0] 55 | document = options.args[1] 56 | if options.verbose: 57 | quiet = '0' 58 | else: 59 | quiet = '1' 60 | remaining_args = options.args[2:] 61 | 62 | (gtkdocdir, styledir) = config.get_dirs(options.uninstalled) 63 | 64 | res = run_xsltproc(options, [ 65 | '--nonet', 66 | '--xinclude', 67 | '--stringparam', 68 | 'gtkdoc.bookname', 69 | module, 70 | '--stringparam', 71 | 'gtkdoc.version', 72 | config.version, 73 | '--stringparam', 74 | 'chunk.quietly', 75 | quiet, 76 | '--stringparam', 77 | 'chunker.output.quiet', 78 | quiet] + remaining_args + [gtkdocdir + '/gtk-doc.xsl', document]) 79 | 80 | # profiling 81 | if os.environ.get("GTKDOC_PROFILE", '') != '': 82 | subprocess.check_call('cat profile.txt | gprof2dot.py -e 0.01 -n 0.01 | dot -Tpng -o profile.png', shell=True) 83 | 84 | # copy navigation images and stylesheets to html directory ... 85 | for f in glob(styledir + '/*.png') + glob(styledir + '/*.css'): 86 | shutil.copy(f, '.') 87 | 88 | with open('../html.stamp', 'w') as h: 89 | h.write('timestamp') 90 | return res 91 | -------------------------------------------------------------------------------- /gtkdoc/mkman.py: -------------------------------------------------------------------------------- 1 | # -*- python; coding: utf-8 -*- 2 | # 3 | # gtk-doc - GTK DocBook documentation generator. 4 | # Copyright (C) 1998 Owen Taylor 5 | # 2001-2005 Damon Chaplin 6 | # 2009-2017 Stefan Sauer 7 | # 2017 Jussi Pakkanen 8 | # 9 | # This program is free software; you can redistribute it and/or modify 10 | # it under the terms of the GNU General Public License as published by 11 | # the Free Software Foundation; either version 2 of the License, or 12 | # (at your option) any later version. 13 | # 14 | # This program is distributed in the hope that it will be useful, 15 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 16 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 | # GNU General Public License for more details. 18 | # 19 | # You should have received a copy of the GNU General Public License 20 | # along with this program; if not, write to the Free Software 21 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 22 | # 23 | 24 | import logging 25 | import subprocess 26 | 27 | from . import config 28 | 29 | 30 | def run(options): 31 | logging.info('options: %s', str(options.__dict__)) 32 | 33 | module = options.args[0] 34 | document = options.args[1] 35 | if options.verbose: 36 | quiet = '0' 37 | else: 38 | quiet = '1' 39 | 40 | # we could do "--path $PWD " to avoid needing rewriting entities that 41 | # are copied from the header into docs under xml 42 | path_arg = [] 43 | for path in options.path: 44 | path_arg += ['--path', path] 45 | 46 | # would it make sense to create man pages only for certain refentries 47 | # e.g. for tools 48 | # see http://bugzilla.gnome.org/show_bug.cgi?id=467488 49 | return subprocess.call([config.xsltproc] + path_arg + [ 50 | '--nonet', 51 | '--xinclude', 52 | '--stringparam', 53 | 'gtkdoc.bookname', 54 | module, 55 | '--stringparam', 56 | 'gtkdoc.version', 57 | config.version, 58 | '--stringparam', 59 | 'chunk.quietly ', 60 | quiet, 61 | '--stringparam', 62 | 'chunker.output.quiet', 63 | quiet, 64 | 'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl', 65 | document]) 66 | -------------------------------------------------------------------------------- /gtkdoc_uninstalled.py.in: -------------------------------------------------------------------------------- 1 | import sys 2 | 3 | sourcedir = "@sourcedir@" 4 | builddir = "@builddir@" 5 | sys.path.append(sourcedir) 6 | -------------------------------------------------------------------------------- /help/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | if HAVE_YELP_TOOLS 4 | SUBDIRS = manual 5 | endif 6 | 7 | EXTRA_DIST = meson.build 8 | 9 | -include $(top_srcdir)/git.mk 10 | -------------------------------------------------------------------------------- /help/manual/LINGUAS: -------------------------------------------------------------------------------- 1 | # Please keep this list sorted alphabetically. 2 | bn_IN 3 | cs 4 | de 5 | el 6 | en_GB 7 | es 8 | eu 9 | fr 10 | gl 11 | gu 12 | hu 13 | pt_BR 14 | sl 15 | sv 16 | ta 17 | te 18 | zh_CN 19 | -------------------------------------------------------------------------------- /help/manual/Makefile.am: -------------------------------------------------------------------------------- 1 | if HAVE_YELP_TOOLS 2 | @YELP_HELP_RULES@ 3 | endif 4 | 5 | HELP_ID = gtk-doc-manual 6 | 7 | HELP_FILES = \ 8 | index.docbook \ 9 | fdl-appendix.xml 10 | 11 | HELP_LINGUAS = bn_IN cs de el en_GB es eu fr gl gu hu pt_BR sl sv ta te zh_CN 12 | 13 | CLEANFILES = $(_HELP_LC_FILES) $(_HELP_LC_STAMPS) $(_HELP_MOFILES) 14 | 15 | GITIGNOREFILES = ??_??/$(HELP_ID).xml ??/$(HELP_ID).xml 16 | 17 | EXTRA_DIST = meson.build 18 | 19 | -include $(top_srcdir)/git.mk 20 | -------------------------------------------------------------------------------- /help/manual/meson.build: -------------------------------------------------------------------------------- 1 | gtkdoc_help_sources = [ 2 | 'index.docbook', 3 | 'fdl-appendix.xml', 4 | ] 5 | 6 | gnome.yelp( 7 | meson.project_name() + '-manual', 8 | sources: gtkdoc_help_sources, 9 | ) 10 | -------------------------------------------------------------------------------- /help/meson.build: -------------------------------------------------------------------------------- 1 | if get_option('yelp_manual') 2 | subdir('manual') 3 | endif 4 | -------------------------------------------------------------------------------- /m4/ax_python_module.m4: -------------------------------------------------------------------------------- 1 | # =========================================================================== 2 | # https://www.gnu.org/software/autoconf-archive/ax_python_module.html 3 | # =========================================================================== 4 | # 5 | # SYNOPSIS 6 | # 7 | # AX_PYTHON_MODULE(modname[, fatal, python]) 8 | # 9 | # DESCRIPTION 10 | # 11 | # Checks for Python module. 12 | # 13 | # If fatal is non-empty then absence of a module will trigger an error. 14 | # The third parameter can either be "python" for Python 2 or "python3" for 15 | # Python 3; defaults to Python 3. 16 | # 17 | # LICENSE 18 | # 19 | # Copyright (c) 2008 Andrew Collier 20 | # 21 | # Copying and distribution of this file, with or without modification, are 22 | # permitted in any medium without royalty provided the copyright notice 23 | # and this notice are preserved. This file is offered as-is, without any 24 | # warranty. 25 | 26 | #serial 9 27 | 28 | AU_ALIAS([AC_PYTHON_MODULE], [AX_PYTHON_MODULE]) 29 | AC_DEFUN([AX_PYTHON_MODULE],[ 30 | if test -z $PYTHON; 31 | then 32 | if test -z "$3"; 33 | then 34 | PYTHON="python3" 35 | else 36 | PYTHON="$3" 37 | fi 38 | fi 39 | PYTHON_NAME=`basename $PYTHON` 40 | AC_MSG_CHECKING($PYTHON_NAME module: $1) 41 | $PYTHON -c "import $1" 2>/dev/null 42 | if test $? -eq 0; 43 | then 44 | AC_MSG_RESULT(yes) 45 | eval AS_TR_CPP(HAVE_PYMOD_$1)=yes 46 | else 47 | AC_MSG_RESULT(no) 48 | eval AS_TR_CPP(HAVE_PYMOD_$1)=no 49 | # 50 | if test -n "$2" 51 | then 52 | AC_MSG_ERROR(failed to find required module $1) 53 | exit 1 54 | fi 55 | fi 56 | ]) 57 | -------------------------------------------------------------------------------- /m4/gtkdoc_jh_check_xml_catalog.m4: -------------------------------------------------------------------------------- 1 | dnl Checks if a particular URI appears in the XML catalog 2 | dnl Usage: 3 | dnl JH_CHECK_XML_CATALOG(URI, [FRIENDLY-NAME], [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) 4 | AC_DEFUN([JH_CHECK_XML_CATALOG], 5 | [ 6 | AC_REQUIRE([JH_PATH_XML_CATALOG],[JH_PATH_XML_CATALOG(,[:])])dnl 7 | AC_MSG_CHECKING([for ifelse([$2],,[$1],[$2]) in XML catalog]) 8 | if $jh_found_xmlcatalog && \ 9 | AC_RUN_LOG([$XMLCATALOG --noout "$XML_CATALOG_FILE" "$1" >&2]); then 10 | AC_MSG_RESULT([found]) 11 | ifelse([$3],,,[$3]) 12 | else 13 | AC_MSG_RESULT([not found]) 14 | ifelse([$4],,[AC_MSG_ERROR([could not find ifelse([$2],,[$1],[$2]) in XML catalog])],[$4]) 15 | fi 16 | ]) 17 | -------------------------------------------------------------------------------- /m4/gtkdoc_jh_path_xml_catalog.m4: -------------------------------------------------------------------------------- 1 | dnl Checks the location of the XML Catalog 2 | dnl Usage: 3 | dnl JH_PATH_XML_CATALOG([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) 4 | dnl Defines XMLCATALOG and XML_CATALOG_FILE substitutions 5 | AC_DEFUN([JH_PATH_XML_CATALOG], 6 | [ 7 | dnl check for the presence of the XML catalog 8 | AC_ARG_WITH([xml-catalog], 9 | AS_HELP_STRING([--with-xml-catalog=CATALOG], 10 | [path to xml catalog to use]),, 11 | [with_xml_catalog='']) 12 | AC_MSG_CHECKING([for XML catalog]) 13 | if test -n "$with_xml_catalog"; then 14 | dnl path was explicitly given. check that it exists. 15 | if test -f "$with_xml_catalog"; then 16 | jh_found_xmlcatalog=true 17 | else 18 | jh_found_xmlcatalog=false 19 | fi 20 | else 21 | dnl if one was not explicitly specified, try some guesses 22 | dnl we look first in /etc/xml/catalog, then XDG_DATA_DIRS/xml/catalog 23 | if test -z "$XDG_DATA_DIRS"; then 24 | dnl if we have no XDG_DATA_DIRS, use the default 25 | jh_xml_catalog_searchdirs="/etc:/usr/local/share:/usr/share" 26 | else 27 | jh_xml_catalog_searchdirs="/etc:$XDG_DATA_DIRS" 28 | fi 29 | jh_found_xmlcatalog=false 30 | dnl take care to iterate based on ':', allowing whitespace to appear in paths 31 | jh_xml_catalog_saved_ifs="$IFS" 32 | IFS=':' 33 | for d in $jh_xml_catalog_searchdirs; do 34 | if test -f "$d/xml/catalog"; then 35 | with_xml_catalog="$d/xml/catalog" 36 | jh_found_xmlcatalog=true 37 | break 38 | fi 39 | done 40 | IFS="$jh_xml_catalog_saved_ifs" 41 | fi 42 | if $jh_found_xmlcatalog; then 43 | AC_MSG_RESULT([$with_xml_catalog]) 44 | else 45 | AC_MSG_RESULT([not found]) 46 | fi 47 | XML_CATALOG_FILE="$with_xml_catalog" 48 | AC_SUBST([XML_CATALOG_FILE]) 49 | 50 | dnl check for the xmlcatalog program 51 | AC_PATH_PROG(XMLCATALOG, xmlcatalog, no) 52 | if test "x$XMLCATALOG" = xno; then 53 | jh_found_xmlcatalog=false 54 | fi 55 | 56 | if $jh_found_xmlcatalog; then 57 | ifelse([$1],,[:],[$1]) 58 | else 59 | ifelse([$2],,[AC_MSG_ERROR([could not find XML catalog])],[$2]) 60 | fi 61 | ]) 62 | -------------------------------------------------------------------------------- /meson_options.txt: -------------------------------------------------------------------------------- 1 | option('autotools_support', 2 | type: 'boolean', value: true, 3 | description: 'Install autotools macros') 4 | option('cmake_support', 5 | type: 'boolean', value: true, 6 | description: 'Install CMake macros') 7 | option('yelp_manual', 8 | type: 'boolean', value: true, 9 | description: 'Build the user manual (requires yelp-tools)') 10 | option('tests', 11 | type: 'boolean', value: true, 12 | description: 'Build the test suite (requires glib)') 13 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | pygments 2 | -------------------------------------------------------------------------------- /style/COPYING: -------------------------------------------------------------------------------- 1 | This style subdirectory of this package contains a number of images and a css 2 | stylesheet used in the formatted output. 3 | 4 | The images were created primarily by William Jon McCann in these commits 5 | * 939576cd24da19e15eed97c937480514eb373669 6 | * 0fab530ad580011d8fee87755a37d180392e9970 7 | 8 | The stylesheet was added by Matthias Clasen in commit 9 | * 07971801371971f69b03c190d91aab4e5177e5c5 10 | 11 | These images and the stylesheet are licensed under the terms of the GNU GPL. 12 | 13 | As a special exception to the GNU General Public License, if you distribute 14 | copies of your document formatted by the tools in this package, you may 15 | redistribute unmodified copies of any images and style sheets used or 16 | referenced in that formatted copy without restriction. 17 | 18 | -------------------------------------------------------------------------------- /style/home.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GNOME/gtk-doc/6fafd62a12a86b774c3a48c00ee2c7bda1459ce4/style/home.png -------------------------------------------------------------------------------- /style/left-insensitive.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GNOME/gtk-doc/6fafd62a12a86b774c3a48c00ee2c7bda1459ce4/style/left-insensitive.png -------------------------------------------------------------------------------- /style/left.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GNOME/gtk-doc/6fafd62a12a86b774c3a48c00ee2c7bda1459ce4/style/left.png -------------------------------------------------------------------------------- /style/meson.build: -------------------------------------------------------------------------------- 1 | gtkdoc_style_data = [ 2 | 'home.png', 3 | 'left.png', 4 | 'left-insensitive.png', 5 | 'right.png', 6 | 'right-insensitive.png', 7 | 'style.css', 8 | 'up.png', 9 | 'up-insensitive.png', 10 | ] 11 | 12 | install_data( 13 | gtkdoc_style_data, 14 | install_dir: pkgdatadir, 15 | ) -------------------------------------------------------------------------------- /style/right-insensitive.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GNOME/gtk-doc/6fafd62a12a86b774c3a48c00ee2c7bda1459ce4/style/right-insensitive.png -------------------------------------------------------------------------------- /style/right.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GNOME/gtk-doc/6fafd62a12a86b774c3a48c00ee2c7bda1459ce4/style/right.png -------------------------------------------------------------------------------- /style/up-insensitive.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GNOME/gtk-doc/6fafd62a12a86b774c3a48c00ee2c7bda1459ce4/style/up-insensitive.png -------------------------------------------------------------------------------- /style/up.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GNOME/gtk-doc/6fafd62a12a86b774c3a48c00ee2c7bda1459ce4/style/up.png -------------------------------------------------------------------------------- /tests/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | SUBDIRS = 4 | TESTS = \ 5 | tools.sh check.py common.py highlight.py mkdb.py mk_to_db.py mkhtml2.py \ 6 | scan.py 7 | 8 | if BUILD_TESTS 9 | # we need to run '.' last so that sanity processes the generated docs 10 | # maybe move it to a subdir? 11 | SUBDIRS += annotations bugs empty fail gobject program repro . 12 | TESTS += annotations.sh bugs.sh empty.sh fail.sh gobject.sh program.sh 13 | endif 14 | 15 | TESTS_ENVIRONMENT = \ 16 | BUILDDIR=$(abs_builddir) \ 17 | SRCDIR=$(abs_srcdir) \ 18 | ABS_TOP_BUILDDIR=$(abs_top_builddir) \ 19 | ABS_TOP_SRCDIR=$(abs_top_srcdir) \ 20 | PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ 21 | PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ 22 | GLIB_PREFIX="$(glib_prefix)" 23 | 24 | TEST_EXTENSIONS = .py 25 | PY_LOG_COMPILER = $(PYTHON) 26 | 27 | EXTRA_DIST = gtkdoctest.sh sanity.sh $(TESTS) 28 | 29 | # run any given test by running make .check 30 | %.check: % 31 | @$(TESTS_ENVIRONMENT) \ 32 | ./$* 33 | 34 | snapshot: 35 | @for dir in $(SUBDIRS); do \ 36 | rm -rf $$dir/docs/html.ref; \ 37 | if test -d $$dir/docs/html; then \ 38 | cp -r $$dir/docs/html $$dir/docs/html.ref; \ 39 | fi; \ 40 | rm -rf $$dir/docs/xml.ref; \ 41 | if test -d $$dir/docs/xml; then \ 42 | cp -r $$dir/docs/xml $$dir/docs/xml.ref; \ 43 | fi; \ 44 | done 45 | 46 | coverage: 47 | @python3-coverage erase; \ 48 | for f in *.py; do \ 49 | $(TESTS_ENVIRONMENT) python3-coverage run -a $$f; \ 50 | done; \ 51 | python3-coverage html --include="*/gtkdoc/*.py"; \ 52 | python3-coverage report --include="*/gtkdoc/*.py" 53 | 54 | EXTRA_DIST += \ 55 | gtkdocentities.ent.in \ 56 | helpers/gtkdoc_check_runner.py \ 57 | helpers/gtkdoc_fixxref_runner.py \ 58 | helpers/gtkdoc_mkdb_runner.py \ 59 | helpers/gtkdoc_mkhtml_runner.py \ 60 | helpers/gtkdoc_scan_runner.py \ 61 | helpers/gtkdoc_scangobj_runner.py \ 62 | helpers/meson.build \ 63 | meson.build 64 | 65 | .PHONY: snapshot 66 | 67 | -include $(top_srcdir)/git.mk 68 | -------------------------------------------------------------------------------- /tests/annotations.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -e 4 | 5 | gtkdoctest.sh annotations 6 | sanity.sh annotations 7 | -------------------------------------------------------------------------------- /tests/annotations/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | SUBDIRS = . src docs 4 | 5 | if BUILD_TESTS 6 | 7 | check-local: clean 8 | 9 | endif 10 | 11 | EXTRA_DIST = meson.build 12 | 13 | -include $(top_srcdir)/git.mk 14 | -------------------------------------------------------------------------------- /tests/annotations/docs/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | # We require automake 1.6 at least. 4 | AUTOMAKE_OPTIONS = 1.6 5 | 6 | # The name of the module, e.g. 'glib'. 7 | DOC_MODULE=tester 8 | 9 | # The top-level SGML file. You can change this if you want to. 10 | DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml 11 | 12 | # The directory containing the source code. Relative to $(srcdir). 13 | # gtk-doc will search all .c & .h files beneath here for inline comments 14 | # documenting the functions and macros. 15 | DOC_SOURCE_DIR=$(top_srcdir)/tests/annotations/src 16 | 17 | # Extra options to pass to gtkdoc-scangobj. Not normally needed. 18 | SCANGOBJ_OPTIONS= 19 | 20 | # Extra options to supply to gtkdoc-scan. 21 | SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ 22 | --ignore-decorators="GLIB_VAR" 23 | 24 | # Extra options to supply to gtkdoc-mkdb. 25 | MKDB_OPTIONS=--xml-mode 26 | 27 | # Extra options to supply to gtkdoc-mkhtml 28 | MKHTML_OPTIONS= 29 | 30 | # Extra options to supply to gtkdoc-fixref. Not normally needed. 31 | # --html-dir=$(HTML_DIR) 32 | FIXXREF_OPTIONS=--extra-dir=$(glib_prefix)/share/gtk-doc/html 33 | 34 | # Used for dependencies. The docs will be rebuilt if any of these change. 35 | HFILE_GLOB=$(top_srcdir)/tests/annotations/src/*.h 36 | CFILE_GLOB=$(top_srcdir)/tests/annotations/src/*.c 37 | 38 | # Header files to ignore when scanning. 39 | IGNORE_HFILES=config.h 40 | 41 | # Images to copy into HTML directory. 42 | HTML_IMAGES = 43 | 44 | # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). 45 | # e.g. content_files=running.sgml building.sgml changes-2.0.sgml 46 | content_files = 47 | 48 | # SGML files where gtk-doc abbreviations (#GtkWidget) are expanded 49 | # These files must be listed here *and* in content_files 50 | # e.g. expand_content_files=running.sgml 51 | expand_content_files= 52 | 53 | # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. 54 | # Only needed if you are using gtkdoc-scangobj to dynamically query widget 55 | # signals and properties. 56 | GTKDOC_CFLAGS = -I$(top_srcdir)/tests/annotations/src $(TEST_DEPS_CFLAGS) 57 | GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/annotations/src/libtester.la 58 | 59 | # include generic part 60 | include $(top_srcdir)/tests/gtk-doc.make 61 | 62 | # Other files to distribute 63 | # e.g. EXTRA_DIST += version.xml.in 64 | EXTRA_DIST += 65 | 66 | CLEANFILES += \ 67 | $(DOC_MODULE)-overrides.txt 68 | 69 | if BUILD_TESTS 70 | TESTS_ENVIRONMENT = \ 71 | DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ 72 | PATH=$(abs_top_builddir):$(srcdir):$(PATH) 73 | endif 74 | 75 | EXTRA_DIST += meson.build 76 | EXTRA_DIST += xml/meson.build 77 | 78 | -include $(top_srcdir)/git.mk 79 | -------------------------------------------------------------------------------- /tests/annotations/docs/meson.build: -------------------------------------------------------------------------------- 1 | annotations_test_source_dir = join_paths( 2 | srcdir, 3 | 'tests', 4 | 'annotations', 5 | 'src' 6 | ) 7 | 8 | annotations_test_docs_dir = join_paths( 9 | srcdir, 10 | 'tests', 11 | 'annotations', 12 | 'docs' 13 | ) 14 | 15 | annotations_test_output_dir = join_paths( 16 | builddir, 17 | 'tests', 18 | 'annotations', 19 | 'docs' 20 | ) 21 | 22 | annotations_test_html_data = [] 23 | 24 | subdir('xml') 25 | 26 | test( 27 | 'test-annotations-scan', 28 | python_prg, 29 | workdir: annotations_test_docs_dir, 30 | is_parallel: false, 31 | args: [ 32 | gtkdoc_scan_runner_script, 33 | '--binary-dir=@0@'.format(builddir), 34 | '--change-dir=@0@'.format(annotations_test_output_dir), 35 | '--module=@0@'.format('tester'), 36 | '--source-dir=@0@'.format(annotations_test_source_dir), 37 | '--ignore-headers=config.h', 38 | '--deprecated-guards=GTKDOC_TESTER_DISABLE_DEPRECATED', 39 | '--ignore-decorators=GLIB_VAR', 40 | ], 41 | ) 42 | 43 | test( 44 | 'test-annotations-mkdb', 45 | python_prg, 46 | workdir: annotations_test_output_dir, 47 | is_parallel: false, 48 | args: [ 49 | gtkdoc_mkdb_runner_script, 50 | '--binary-dir=@0@'.format(builddir), 51 | '--module=@0@'.format('tester'), 52 | '--source-dir=@0@'.format(annotations_test_source_dir), 53 | '--main-sgml-file=@0@'.format('tester-docs.xml'), 54 | '--output-format=xml', 55 | '--xml-mode', 56 | ], 57 | ) 58 | 59 | foreach style_data: gtkdoc_style_data 60 | annotations_test_html_data += join_paths(srcdir, 'style', style_data) 61 | endforeach 62 | 63 | test( 64 | 'test-annotations-mkhtml', 65 | python_prg, 66 | workdir: annotations_test_output_dir, 67 | is_parallel: false, 68 | args: [ 69 | gtkdoc_mkhtml_runner_script, 70 | '--binary-dir=@0@'.format(builddir), 71 | '--change-dir=@0@'.format(join_paths(annotations_test_output_dir, 'html')), 72 | '--html-assets=@0@'.format('@@'.join(annotations_test_html_data)), 73 | '@0@'.format('tester'), 74 | '@0@'.format(join_paths('..', 'tester-docs.xml')), 75 | '--uninstalled', 76 | '--path=@0@'.format(':'.join([ 77 | annotations_test_docs_dir, 78 | srcdir]) 79 | ), 80 | ], 81 | ) 82 | 83 | test( 84 | 'test-annotations-fixxref', 85 | python_prg, 86 | workdir: annotations_test_output_dir, 87 | is_parallel: false, 88 | args: [ 89 | gtkdoc_fixxref_runner_script, 90 | '--binary-dir=@0@'.format(builddir), 91 | '--module=@0@'.format('tester'), 92 | '--module-dir=@0@'.format('html'), 93 | '--extra-dir=@0@'.format(glib_docpath), 94 | '--extra-dir=@0@'.format(gobject_docpath), 95 | ], 96 | ) 97 | 98 | test( 99 | 'test-annotations-check', 100 | python_prg, 101 | workdir: annotations_test_docs_dir, 102 | is_parallel: false, 103 | args: [ 104 | gtkdoc_check_runner_script, 105 | '--binary-dir=@0@'.format(builddir), 106 | '--input-dir=@0@'.format(annotations_test_docs_dir), 107 | '--output-dir=@0@'.format(annotations_test_output_dir), 108 | ], 109 | ) -------------------------------------------------------------------------------- /tests/annotations/docs/tester-docs.xml: -------------------------------------------------------------------------------- 1 | 2 | 6 | 7 | %gtkdocentities; 8 | ]> 9 | 10 | 11 | &package_name; Reference Manual 12 | 13 | for &package_string;. 14 | The latest version of this documentation can be found on-line at 15 | http://[SERVER]/&package_name;/. 16 | 17 | 18 | 19 | 20 | API Reference 21 | 22 | Tests 23 | 24 | 25 | 26 | 27 | 28 | Appendix 29 | 30 | 31 | API Index 32 | 33 | 34 | 35 | Index of deprecated API 36 | 37 | 38 | 39 | 40 | Glossary 41 | X 42 | 43 | XML 44 | 45 | Extensible Markup Language 46 | 47 | 48 | 49 | XSL 50 | 51 | XML Stylesheet Language 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | -------------------------------------------------------------------------------- /tests/annotations/docs/tester-sections.txt: -------------------------------------------------------------------------------- 1 |
2 | tester 3 | GtkdocTester 4 | GtkdocAnnotation 5 | annotation_array_length 6 | annotation_allow_none 7 | annotation_nullable 8 | annotation_not_nullable 9 | annotation_elementtype 10 | annotation_elementtype_transfer 11 | annotation_elementtype_returns 12 | annotation_outparams 13 | annotation_outparams_nullable 14 | annotation_outparams_not_nullable 15 | annotation_outparams_optional 16 | annotation_outparams_not_optional 17 | annotation_outparams_optional_nullable 18 | annotation_outparams_not_optional_nullable 19 | annotation_outparams_optional_not_nullable 20 | annotation_outparams_not_optional_not_nullable 21 | annotation_skip 22 | annotation_skip_return 23 | annotation_scope 24 | annotation_rename_to 25 | annotation_attributes_single 26 | annotation_attributes_single_eq 27 | stability_unstable 28 | annotation_multiline_on_function 29 | annotation_multiline_on_function2 30 | 31 | 32 |
33 | 34 | -------------------------------------------------------------------------------- /tests/annotations/docs/xml/meson.build: -------------------------------------------------------------------------------- 1 | configure_file( 2 | input: join_paths(srcdir, 'tests', 'gtkdocentities.ent.in'), 3 | output: 'gtkdocentities.ent', 4 | configuration: binary_in, 5 | ) 6 | -------------------------------------------------------------------------------- /tests/annotations/meson.build: -------------------------------------------------------------------------------- 1 | subdir('docs') -------------------------------------------------------------------------------- /tests/annotations/src/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | if BUILD_TESTS 4 | 5 | noinst_LTLIBRARIES = libtester.la 6 | 7 | libtester_la_SOURCES = tester.c tester.h 8 | #libtester_la_LIBADD = $(TEST_DEPS_LIBS) 9 | 10 | AM_CPPFLAGS = $(TEST_DEPS_CFLAGS) 11 | 12 | endif 13 | 14 | 15 | -include $(top_srcdir)/git.mk 16 | -------------------------------------------------------------------------------- /tests/annotations/src/tester.h: -------------------------------------------------------------------------------- 1 | #ifndef GTKDOC_TESTER_H 2 | #define GTKDOC_TESTER_H 3 | 4 | #include 5 | #include 6 | 7 | /** 8 | * GtkdocAnnotation: 9 | * @that: (allow-none): eventually points to something 10 | * 11 | * small struct 12 | */ 13 | struct _GtkdocAnnotation { 14 | gpointer that; 15 | }; 16 | 17 | void annotation_array_length (GObject *list, gint n_columns, GType *types); 18 | 19 | gchar * annotation_allow_none (const gchar *uri, const gchar *label); 20 | gchar * annotation_nullable (const gchar *uri, const gchar *label); 21 | gchar * annotation_not_nullable (const gchar *uri, const gchar *label); 22 | 23 | gboolean annotation_elementtype (const GList *list); 24 | gboolean annotation_elementtype_transfer (const GList *list); 25 | GList *annotation_elementtype_returns (void); 26 | 27 | gboolean annotation_outparams (GList **list); 28 | gboolean annotation_outparams_optional (GList **list); 29 | gboolean annotation_outparams_not_optional (GList **list); 30 | gboolean annotation_outparams_nullable (GList **list); 31 | gboolean annotation_outparams_not_nullable (GList **list); 32 | gboolean annotation_outparams_optional_nullable (GList **list); 33 | gboolean annotation_outparams_not_optional_nullable (GList **list); 34 | gboolean annotation_outparams_optional_not_nullable (GList **list); 35 | gboolean annotation_outparams_not_optional_not_nullable (GList **list); 36 | 37 | void annotation_skip (GList *list); 38 | gboolean annotation_skip_return (GList *list); 39 | 40 | void annotation_scope (GCallback *callback, gpointer user_data); 41 | 42 | void annotation_rename_to (void); 43 | 44 | void annotation_attributes_single (void); 45 | void annotation_attributes_single_eq (void); 46 | 47 | void stability_unstable(void); 48 | 49 | void annotation_multiline_on_function (void); 50 | void annotation_multiline_on_function2 (void); 51 | 52 | #endif // GTKDOC_TESTER_H 53 | 54 | -------------------------------------------------------------------------------- /tests/bugs.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -e 4 | 5 | gtkdoctest.sh bugs 6 | sanity.sh bugs 7 | -------------------------------------------------------------------------------- /tests/bugs/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | SUBDIRS = . src docs 4 | 5 | if BUILD_TESTS 6 | 7 | check-local: clean 8 | 9 | endif 10 | 11 | EXTRA_DIST = meson.build 12 | 13 | -include $(top_srcdir)/git.mk 14 | -------------------------------------------------------------------------------- /tests/bugs/docs/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | # We require automake 1.6 at least. 4 | AUTOMAKE_OPTIONS = 1.6 5 | 6 | # The name of the module, e.g. 'glib'. 7 | DOC_MODULE=tester 8 | 9 | # The top-level SGML file. You can change this if you want to. 10 | DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml 11 | 12 | # The directory containing the source code. Relative to $(srcdir). 13 | # gtk-doc will search all .c & .h files beneath here for inline comments 14 | # documenting the functions and macros. 15 | DOC_SOURCE_DIR=$(top_srcdir)/tests/bugs/src 16 | 17 | # Extra options to pass to gtkdoc-scangobj. Not normally needed. 18 | SCANGOBJ_OPTIONS= 19 | 20 | # Extra options to supply to gtkdoc-scan. 21 | SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ 22 | --ignore-decorators='GLIB_VAR|GTKDOC_GNUC_CONST|BUG_711598_DEPRECATED_FOR()|MY_DEPRECATED_FOR()' \ 23 | --rebuild-types 24 | 25 | # Extra options to supply to gtkdoc-mkdb. 26 | MKDB_OPTIONS=--xml-mode 27 | 28 | # Extra options to supply to gtkdoc-mkhtml 29 | MKHTML_OPTIONS= 30 | 31 | # Extra options to supply to gtkdoc-fixref. Not normally needed. 32 | # --html-dir=$(HTML_DIR) 33 | FIXXREF_OPTIONS=--extra-dir=$(glib_prefix)/share/gtk-doc/html 34 | 35 | # Used for dependencies. The docs will be rebuilt if any of these change. 36 | HFILE_GLOB=$(top_srcdir)/tests/bugs/src/*.h 37 | CFILE_GLOB=$(top_srcdir)/tests/bugs/src/*.c 38 | 39 | # Header files to ignore when scanning. 40 | IGNORE_HFILES=config.h 41 | 42 | # Images to copy into HTML directory. 43 | HTML_IMAGES = 44 | 45 | # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). 46 | # e.g. content_files=running.sgml building.sgml changes-2.0.sgml 47 | content_files = 48 | 49 | # SGML files where gtk-doc abbreviations (#GtkWidget) are expanded 50 | # These files must be listed here *and* in content_files 51 | # e.g. expand_content_files=running.sgml 52 | expand_content_files= 53 | 54 | # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. 55 | # Only needed if you are using gtkdoc-scangobj to dynamically query widget 56 | # signals and properties. 57 | GTKDOC_CFLAGS = -I$(top_srcdir)/tests/bugs/src $(TEST_DEPS_CFLAGS) 58 | GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/bugs/src/libtester.la 59 | 60 | # include generic part 61 | include $(top_srcdir)/tests/gtk-doc.make 62 | 63 | # Other files to distribute 64 | # e.g. EXTRA_DIST += version.xml.in 65 | EXTRA_DIST += 66 | 67 | CLEANFILES += \ 68 | $(DOC_MODULE)-overrides.txt \ 69 | $(DOC_MODULE).types 70 | 71 | if BUILD_TESTS 72 | TESTS_ENVIRONMENT = \ 73 | DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ 74 | PATH=$(abs_top_builddir):$(srcdir):$(PATH) 75 | endif 76 | 77 | EXTRA_DIST += meson.build 78 | EXTRA_DIST += xml/meson.build 79 | 80 | -include $(top_srcdir)/git.mk 81 | -------------------------------------------------------------------------------- /tests/bugs/docs/meson.build: -------------------------------------------------------------------------------- 1 | bugs_test_source_dir = join_paths( 2 | srcdir, 3 | 'tests', 4 | 'bugs', 5 | 'src' 6 | ) 7 | 8 | bugs_test_docs_dir = join_paths( 9 | srcdir, 10 | 'tests', 11 | 'bugs', 12 | 'docs' 13 | ) 14 | 15 | bugs_test_output_dir = join_paths( 16 | builddir, 17 | 'tests', 18 | 'bugs', 19 | 'docs' 20 | ) 21 | 22 | bugs_test_html_data = [] 23 | 24 | subdir('xml') 25 | 26 | fs.copyfile(join_paths(bugs_test_docs_dir, 'tester-sections.txt')) 27 | 28 | test( 29 | 'test-bugs-scan', 30 | python_prg, 31 | workdir: bugs_test_docs_dir, 32 | is_parallel: false, 33 | args: [ 34 | gtkdoc_scan_runner_script, 35 | '--binary-dir=@0@'.format(builddir), 36 | '--change-dir=@0@'.format(bugs_test_output_dir), 37 | '--module=@0@'.format('tester'), 38 | '--source-dir=@0@'.format(bugs_test_source_dir), 39 | '--ignore-headers=config.h', 40 | '--deprecated-guards=GTKDOC_TESTER_DISABLE_DEPRECATED', 41 | '--ignore-decorators=GLIB_VAR|GTKDOC_GNUC_CONST|BUG_711598_DEPRECATED_FOR()|MY_DEPRECATED_FOR()', 42 | '--rebuild-types', 43 | ], 44 | ) 45 | 46 | test( 47 | 'test-bugs-mkdb', 48 | python_prg, 49 | workdir: bugs_test_output_dir, 50 | is_parallel: false, 51 | args: [ 52 | gtkdoc_mkdb_runner_script, 53 | '--binary-dir=@0@'.format(builddir), 54 | '--module=@0@'.format('tester'), 55 | '--source-dir=@0@'.format(bugs_test_source_dir), 56 | '--main-sgml-file=@0@'.format('tester-docs.xml'), 57 | '--output-format=xml', 58 | '--xml-mode', 59 | ], 60 | ) 61 | 62 | foreach style_data: gtkdoc_style_data 63 | bugs_test_html_data += join_paths(srcdir, 'style', style_data) 64 | endforeach 65 | 66 | test( 67 | 'test-bugs-mkhtml', 68 | python_prg, 69 | workdir: bugs_test_output_dir, 70 | is_parallel: false, 71 | args: [ 72 | gtkdoc_mkhtml_runner_script, 73 | '--binary-dir=@0@'.format(builddir), 74 | '--change-dir=@0@'.format(join_paths(bugs_test_output_dir, 'html')), 75 | '--html-assets=@0@'.format('@@'.join(bugs_test_html_data)), 76 | '@0@'.format('tester'), 77 | '@0@'.format(join_paths('..', 'tester-docs.xml')), 78 | '--uninstalled', 79 | '--path=@0@'.format(':'.join([ 80 | bugs_test_docs_dir, 81 | srcdir]) 82 | ), 83 | ], 84 | ) 85 | 86 | test( 87 | 'test-bugs-fixxref', 88 | python_prg, 89 | workdir: bugs_test_output_dir, 90 | is_parallel: false, 91 | args: [ 92 | gtkdoc_fixxref_runner_script, 93 | '--binary-dir=@0@'.format(builddir), 94 | '--module=@0@'.format('tester'), 95 | '--module-dir=@0@'.format('html'), 96 | '--extra-dir=@0@'.format(glib_docpath), 97 | ], 98 | ) 99 | 100 | test( 101 | 'test-bugs-check', 102 | python_prg, 103 | workdir: bugs_test_docs_dir, 104 | is_parallel: false, 105 | args: [ 106 | gtkdoc_check_runner_script, 107 | '--binary-dir=@0@'.format(builddir), 108 | '--input-dir=@0@'.format(bugs_test_docs_dir), 109 | '--output-dir=@0@'.format(bugs_test_output_dir), 110 | ], 111 | ) 112 | -------------------------------------------------------------------------------- /tests/bugs/docs/tester-docs.xml: -------------------------------------------------------------------------------- 1 | 2 | 6 | 7 | %gtkdocentities; 8 | ]> 9 | 10 | 11 | &package_name; Reference Manual 12 | 13 | for &package_string;. 14 | The latest version of this documentation can be found on-line at 15 | http://[SERVER]/&package_name;/. 16 | 17 | 18 | 19 | 20 | Tests 21 | 22 | 23 | 24 | 25 | API Index 26 | 27 | 28 | 29 | Index of deprecated API 30 | 31 | 32 | 33 | Index of new API in 0.1 34 | 35 | 36 | 37 | -------------------------------------------------------------------------------- /tests/bugs/docs/tester-sections.txt: -------------------------------------------------------------------------------- 1 |
2 | tester 3 | GtkdocTester 4 | BUG_530758 5 | MACRO_FUNCTION 6 | MACRO_VALUE 7 | 8 | Bug165425a 9 | Bug165425b 10 | Bug446648 11 | Bug512154 12 | Bug644291 13 | Bug000000Scope 14 | Bug76 15 | MyDeprecatedEnum 16 | MyNotDeprecatedEnum 17 | MyDeprecatedStruct 18 | MyNotDeprecatedStruct 19 | 20 | bug_000000_va1 21 | BUG_000000_VA2 22 | BUG_000000_VA3 23 | bug_380824 24 | bug_419997 25 | bug_445693 26 | bug_460127 27 | bug_471014 28 | bug_477532 29 | bug_501038 30 | bug_512155a_function_pointer_t 31 | bug_512155b_function_pointer_t 32 | bug_512155c_function_pointer_t 33 | bug_554833 34 | bug_574654a 35 | bug_574654b 36 | bug_580300a_get_type 37 | bug_580300b_get_type 38 | bug_580300c_get_type 39 | bug_580300d_get_type 40 | bug_597937 41 | bug_602518a 42 | bug_602518b 43 | bug_602518c 44 | bug_607445 45 | bug_610257 46 | bug_623968a 47 | bug_623968b 48 | bug_623968c 49 | bug_624200a 50 | bug_624200b 51 | bug_638330 52 | bug_624001a 53 | bug_624001b 54 | bug_624001c 55 | bug_624001d 56 | bug_624001e 57 | bug_711598 58 | bug_749142 59 | deprecation_notice 60 | bug_741941 61 | bug_732689 62 | bug_783420 63 | gst_play_marshal_BUFFER__BOXED 64 | BUG_791928 65 | _ 66 | inline_func_with_macro 67 | 68 | 69 | GTKDOC_GNUC_CONST 70 | G_GNUC_DEPRECATED 71 | G_GNUC_DEPRECATED_FOR 72 | GLIB_DEPRECATED 73 | BUG_711598_DEPRECATED_FOR 74 | bug_554833_new 75 | G_GNUC_NONNULL 76 | MY_DEPRECATED_FOR 77 |
78 | -------------------------------------------------------------------------------- /tests/bugs/docs/xml/meson.build: -------------------------------------------------------------------------------- 1 | configure_file( 2 | input: join_paths(srcdir, 'tests', 'gtkdocentities.ent.in'), 3 | output: 'gtkdocentities.ent', 4 | configuration: binary_in, 5 | ) 6 | -------------------------------------------------------------------------------- /tests/bugs/meson.build: -------------------------------------------------------------------------------- 1 | subdir('docs') -------------------------------------------------------------------------------- /tests/bugs/src/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | if BUILD_TESTS 4 | 5 | noinst_LTLIBRARIES = libtester.la 6 | 7 | libtester_la_SOURCES = tester.c tester.h 8 | #libtester_la_LIBADD = $(TEST_DEPS_LIBS) 9 | 10 | AM_CPPFLAGS = $(TEST_DEPS_CFLAGS) 11 | 12 | endif 13 | 14 | 15 | -include $(top_srcdir)/git.mk 16 | -------------------------------------------------------------------------------- /tests/check.py: -------------------------------------------------------------------------------- 1 | # -*- python -*- 2 | # 3 | # gtk-doc - GTK DocBook documentation generator. 4 | # Copyright (C) 2017 Stefan Sauer 5 | # 6 | # This program is free software; you can redistribute it and/or modify 7 | # it under the terms of the GNU General Public License as published by 8 | # the Free Software Foundation; either version 2 of the License, or 9 | # (at your option) any later version. 10 | # 11 | # This program is distributed in the hope that it will be useful, 12 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 13 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 | # GNU General Public License for more details. 15 | # 16 | # You should have received a copy of the GNU General Public License 17 | # along with this program; if not, write to the Free Software 18 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 19 | # 20 | 21 | import unittest 22 | 23 | from gtkdoc import check 24 | 25 | 26 | class TestCheck(unittest.TestCase): 27 | 28 | def test_grep_finds_token_in_one_line(self): 29 | result = check.grep(r'^(foo)', ['foo'], 'foo') 30 | self.assertEqual('foo', result) 31 | 32 | def test_grep_does_not_find_token(self): 33 | with self.assertRaises(check.FileFormatError) as ctx: 34 | check.grep(r'^(foo)', ['bar'], 'foo') 35 | self.assertEqual(str(ctx.exception), 'foo') 36 | 37 | def test_get_variable_prefers_env(self): 38 | result = check.get_variable({'foo': 'bar'}, ['foo=baz'], 'foo') 39 | self.assertEqual('bar', result) 40 | 41 | def test_get_variable_finds_in_file(self): 42 | result = check.get_variable({}, ['foo=bar'], 'foo') 43 | self.assertEqual('bar', result) 44 | 45 | def test_get_variable_finds_in_file_with_whitespce(self): 46 | result = check.get_variable({}, ['foo = bar'], 'foo') 47 | self.assertEqual('bar', result) 48 | 49 | def test_get_variable_empty_file(self): 50 | with self.assertRaises(check.FileFormatError) as ctx: 51 | check.get_variable({}, [], 'foo') 52 | self.assertEqual(str(ctx.exception), 'foo') 53 | 54 | 55 | if __name__ == '__main__': 56 | unittest.main() 57 | -------------------------------------------------------------------------------- /tests/common.py: -------------------------------------------------------------------------------- 1 | # -*- python -*- 2 | # 3 | # gtk-doc - GTK DocBook documentation generator. 4 | # Copyright (C) 2017 Stefan Sauer 5 | # 6 | # This program is free software; you can redistribute it and/or modify 7 | # it under the terms of the GNU General Public License as published by 8 | # the Free Software Foundation; either version 2 of the License, or 9 | # (at your option) any later version. 10 | # 11 | # This program is distributed in the hope that it will be useful, 12 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 13 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 | # GNU General Public License for more details. 15 | # 16 | # You should have received a copy of the GNU General Public License 17 | # along with this program; if not, write to the Free Software 18 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 19 | # 20 | 21 | from unittest import mock 22 | import unittest 23 | 24 | from gtkdoc import common 25 | 26 | 27 | class TestUpdateFileIfChanged(unittest.TestCase): 28 | 29 | @mock.patch('os.path.exists') 30 | @mock.patch('os.rename') 31 | def test_NoOldFile(self, os_rename, os_path_exists): 32 | os_path_exists.return_value = False 33 | res = common.UpdateFileIfChanged('/old', '/new', False) 34 | os_rename.assert_called_with('/new', '/old') 35 | self.assertTrue(res) 36 | 37 | @mock.patch('os.path.exists') 38 | @mock.patch('builtins.open', mock.mock_open(read_data='bar')) 39 | @mock.patch('os.unlink') 40 | def test_FilesAreTheSame(self, os_unlink, os_path_exists): 41 | os_path_exists.return_value = True 42 | res = common.UpdateFileIfChanged('/old', '/new', False) 43 | os_unlink.assert_called_with('/new') 44 | self.assertFalse(res) 45 | 46 | 47 | class TestGetModuleDocDir(unittest.TestCase): 48 | 49 | @mock.patch('subprocess.check_output') 50 | def test_ReturnsPath(self, subprocess_check_output): 51 | subprocess_check_output.return_value = '/usr' 52 | self.assertEqual(common.GetModuleDocDir('glib-2.0'), '/usr/share/gtk-doc/html') 53 | 54 | 55 | class TestCreateValidSGMLID(unittest.TestCase): 56 | 57 | def test_AlreadyValid(self): 58 | self.assertEqual(common.CreateValidSGMLID('x'), 'x') 59 | 60 | def test_SpecialCharsBecomeDash(self): 61 | self.assertEqual(common.CreateValidSGMLID('x_ y'), 'x--y') 62 | 63 | def test_SpecialCharsGetRemoved(self): 64 | self.assertEqual(common.CreateValidSGMLID('x,;y'), 'xy') 65 | 66 | 67 | if __name__ == '__main__': 68 | unittest.main() 69 | -------------------------------------------------------------------------------- /tests/empty.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -e 4 | 5 | if ! grep -q ^GtkDocTestIf$ empty/docs/tester-sections.txt; then 6 | echo "Test for bug https://bugzilla.gnome.org/show_bug.cgi?id=705633 has failed." 7 | exit 1 8 | fi 9 | 10 | gtkdoctest.sh empty 11 | sanity.sh empty 12 | -------------------------------------------------------------------------------- /tests/empty/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | SUBDIRS = . src docs 4 | 5 | if BUILD_TESTS 6 | 7 | check-local: clean 8 | @rm -f docs/tester-docs.xml 9 | 10 | endif 11 | 12 | EXTRA_DIST = meson.build 13 | 14 | -include $(top_srcdir)/git.mk 15 | -------------------------------------------------------------------------------- /tests/empty/docs/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | # this tests bootstraps gtk-doc, that includes generating a default 4 | # DOC_MAIN_SGML_FILE 5 | # right now that fails with parallel make, as make cannot see that what is a 6 | # dependency for another target is generated as needed 7 | MAKEFLAGS = -j1 8 | 9 | # We require automake 1.6 at least. 10 | AUTOMAKE_OPTIONS = 1.6 11 | 12 | # The name of the module, e.g. 'glib'. 13 | DOC_MODULE=tester 14 | 15 | # The top-level SGML file. You can change this if you want to. 16 | DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml 17 | 18 | # The directory containing the source code. Relative to $(srcdir). 19 | # gtk-doc will search all .c & .h files beneath here for inline comments 20 | # documenting the functions and macros. 21 | DOC_SOURCE_DIR=$(top_srcdir)/tests/empty/src 22 | 23 | # Extra options to pass to gtkdoc-scangobj. Not normally needed. 24 | SCANGOBJ_OPTIONS= 25 | 26 | # Extra options to supply to gtkdoc-scan. 27 | SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ 28 | --rebuild-sections 29 | 30 | # Extra options to supply to gtkdoc-mkdb. 31 | MKDB_OPTIONS=--xml-mode 32 | 33 | # Extra options to supply to gtkdoc-mkhtml 34 | MKHTML_OPTIONS= 35 | 36 | # Extra options to supply to gtkdoc-fixref. Not normally needed. 37 | # --html-dir=$(HTML_DIR) 38 | FIXXREF_OPTIONS=--extra-dir=$(glib_prefix)/share/gtk-doc/html 39 | 40 | # Used for dependencies. The docs will be rebuilt if any of these change. 41 | HFILE_GLOB=$(top_srcdir)/tests/empty/src/*.h 42 | CFILE_GLOB=$(top_srcdir)/tests/empty/src/*.c 43 | 44 | # Header files to ignore when scanning. 45 | IGNORE_HFILES=config.h 46 | 47 | # Images to copy into HTML directory. 48 | HTML_IMAGES = 49 | 50 | # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). 51 | # e.g. content_files=running.sgml building.sgml changes-2.0.sgml 52 | content_files = 53 | 54 | # SGML files where gtk-doc abbreviations (#GtkWidget) are expanded 55 | # These files must be listed here *and* in content_files 56 | # e.g. expand_content_files=running.sgml 57 | expand_content_files= 58 | 59 | # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. 60 | # Only needed if you are using gtkdoc-scangobj to dynamically query widget 61 | # signals and properties. 62 | GTKDOC_CFLAGS = -I$(top_srcdir)/tests/empty/src $(TEST_DEPS_CFLAGS) 63 | GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/empty/src/libtester.la 64 | 65 | # include generic part 66 | include $(top_srcdir)/tests/gtk-doc.make 67 | 68 | # Other files to distribute 69 | # e.g. EXTRA_DIST += version.xml.in 70 | EXTRA_DIST += 71 | 72 | CLEANFILES += \ 73 | $(DOC_MODULE)-overrides.txt \ 74 | $(DOC_MODULE).types 75 | 76 | if BUILD_TESTS 77 | TESTS_ENVIRONMENT = \ 78 | DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ 79 | PATH=$(abs_top_builddir):$(srcdir):$(PATH) 80 | endif 81 | 82 | CLEANFILES += \ 83 | tester-docs.xml \ 84 | tester-sections.txt 85 | 86 | EXTRA_DIST += meson.build 87 | EXTRA_DIST += xml/meson.build 88 | 89 | -include $(top_srcdir)/git.mk 90 | -------------------------------------------------------------------------------- /tests/empty/docs/meson.build: -------------------------------------------------------------------------------- 1 | empty_test_source_dir = join_paths( 2 | srcdir, 3 | 'tests', 4 | 'empty', 5 | 'src' 6 | ) 7 | 8 | empty_test_docs_dir = join_paths( 9 | srcdir, 10 | 'tests', 11 | 'empty', 12 | 'docs' 13 | ) 14 | 15 | empty_test_output_dir = join_paths( 16 | builddir, 17 | 'tests', 18 | 'empty', 19 | 'docs' 20 | ) 21 | 22 | empty_test_html_data = [] 23 | 24 | subdir('xml') 25 | 26 | test( 27 | 'test-empty-scan', 28 | python_prg, 29 | workdir: empty_test_docs_dir, 30 | is_parallel: false, 31 | args: [ 32 | gtkdoc_scan_runner_script, 33 | '--binary-dir=@0@'.format(builddir), 34 | '--change-dir=@0@'.format(empty_test_output_dir), 35 | '--module=@0@'.format('tester'), 36 | '--source-dir=@0@'.format(empty_test_source_dir), 37 | '--ignore-headers=config.h', 38 | '--deprecated-guards=GTKDOC_TESTER_DISABLE_DEPRECATED', 39 | '--rebuild-sections', 40 | ], 41 | ) 42 | 43 | test( 44 | 'test-empty-mkdb', 45 | python_prg, 46 | workdir: empty_test_output_dir, 47 | is_parallel: false, 48 | args: [ 49 | gtkdoc_mkdb_runner_script, 50 | '--binary-dir=@0@'.format(builddir), 51 | '--module=@0@'.format('tester'), 52 | '--source-dir=@0@'.format(empty_test_source_dir), 53 | '--main-sgml-file=@0@'.format('tester-docs.xml'), 54 | '--output-format=xml', 55 | '--xml-mode', 56 | ], 57 | ) 58 | 59 | foreach style_data: gtkdoc_style_data 60 | empty_test_html_data += join_paths(srcdir, 'style', style_data) 61 | endforeach 62 | 63 | test( 64 | 'test-empty-mkhtml', 65 | python_prg, 66 | workdir: empty_test_output_dir, 67 | is_parallel: false, 68 | args: [ 69 | gtkdoc_mkhtml_runner_script, 70 | '--binary-dir=@0@'.format(builddir), 71 | '--change-dir=@0@'.format(join_paths(empty_test_output_dir, 'html')), 72 | '--html-assets=@0@'.format('@@'.join(empty_test_html_data)), 73 | '@0@'.format('tester'), 74 | '@0@'.format(join_paths('..', 'tester-docs.xml')), 75 | '--uninstalled', 76 | '--path=@0@'.format(':'.join([ 77 | empty_test_docs_dir, 78 | srcdir]) 79 | ), 80 | ], 81 | ) 82 | 83 | test( 84 | 'test-empty-fixxref', 85 | python_prg, 86 | workdir: empty_test_output_dir, 87 | is_parallel: false, 88 | args: [ 89 | gtkdoc_fixxref_runner_script, 90 | '--binary-dir=@0@'.format(builddir), 91 | '--module=@0@'.format('tester'), 92 | '--module-dir=@0@'.format('html'), 93 | '--extra-dir=@0@'.format(glib_docpath), 94 | '--extra-dir=@0@'.format(gobject_docpath), 95 | ], 96 | ) 97 | 98 | test( 99 | 'test-empty-check', 100 | python_prg, 101 | workdir: empty_test_docs_dir, 102 | is_parallel: false, 103 | args: [ 104 | gtkdoc_check_runner_script, 105 | '--binary-dir=@0@'.format(builddir), 106 | '--input-dir=@0@'.format(empty_test_docs_dir), 107 | '--output-dir=@0@'.format(empty_test_output_dir), 108 | ], 109 | ) -------------------------------------------------------------------------------- /tests/empty/docs/xml/meson.build: -------------------------------------------------------------------------------- 1 | configure_file( 2 | input: join_paths(srcdir, 'tests', 'gtkdocentities.ent.in'), 3 | output: 'gtkdocentities.ent', 4 | configuration: binary_in, 5 | ) 6 | -------------------------------------------------------------------------------- /tests/empty/meson.build: -------------------------------------------------------------------------------- 1 | subdir('docs') -------------------------------------------------------------------------------- /tests/empty/src/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | if BUILD_TESTS 4 | 5 | noinst_LTLIBRARIES = libtester.la 6 | 7 | libtester_la_SOURCES = tester.c tester.h 8 | #libtester_la_LIBADD = $(TEST_DEPS_LIBS) 9 | 10 | AM_CPPFLAGS = $(TEST_DEPS_CFLAGS) 11 | 12 | endif 13 | 14 | 15 | -include $(top_srcdir)/git.mk 16 | -------------------------------------------------------------------------------- /tests/empty/src/tester.c: -------------------------------------------------------------------------------- 1 | /** 2 | * SECTION:tester 3 | * @short_description: module for gtk-doc unit test 4 | * 5 | * This file contains non-sense code for the sole purpose of testing the docs. 6 | * 7 | * As described in http://bugzilla.gnome.org/show_bug.cgi?id=457077 it 8 | * returns nothing. 9 | */ 10 | 11 | #include "tester.h" 12 | 13 | /** 14 | * test: 15 | * @a: arg 16 | * 17 | * lonely function 18 | */ 19 | void test (gint a) { 20 | } 21 | 22 | /** 23 | * GtkDocTestIf: 24 | * 25 | * test object 26 | */ 27 | /** 28 | * GtkDocTestIfInterface: 29 | * @parent: parent interface type. 30 | * 31 | * test interface 32 | */ 33 | 34 | -------------------------------------------------------------------------------- /tests/empty/src/tester.h: -------------------------------------------------------------------------------- 1 | #ifndef GTKDOC_TESTER_H 2 | #define GTKDOC_TESTER_H 3 | 4 | #include 5 | #include 6 | 7 | /** 8 | * FOO: 9 | * 10 | * The FOO. 11 | * 12 | * Since: 0.1 13 | */ 14 | #define FOO "bar" 15 | 16 | void test (gint a); 17 | 18 | // test for https://bugzilla.gnome.org/show_bug.cgi?id=705633 19 | typedef struct _GtkDocTestIf GtkDocTestIf; 20 | typedef struct _GtkDocTestIfInterface GtkDocTestIfInterface; 21 | 22 | struct _GtkDocTestIfInterface { 23 | GTypeInterface parent; 24 | 25 | }; 26 | 27 | #endif // GTKDOC_TESTER_H 28 | 29 | -------------------------------------------------------------------------------- /tests/fail.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | dir=`dirname $0` 4 | suite="fail" 5 | DOC_MODULE="tester" 6 | failed=0 7 | tested=0 8 | 9 | cd $dir/$suite/docs 10 | 11 | echo "Running suite(s): gtk-doc-$suite"; 12 | 13 | # tests 14 | # check missing section description 15 | # we can't just check for a missing "tester_nodocs" entry 16 | grep >/dev/null "tester_nodocs:long_description" $DOC_MODULE-undocumented.txt 17 | if test $? = 1 ; then failed=`expr $failed + 1`; fi 18 | tested=`expr $tested + 1` 19 | 20 | # check missing section long description 21 | grep >/dev/null "tester_nolongdesc:long_description" $DOC_MODULE-undocumented.txt 22 | if test $? = 1 ; then failed=`expr $failed + 1`; fi 23 | tested=`expr $tested + 1` 24 | 25 | # check missing section short description 26 | grep >/dev/null "tester_noshortdesc:short_description" $DOC_MODULE-undocumented.txt 27 | if test $? = 1 ; then failed=`expr $failed + 1`; fi 28 | tested=`expr $tested + 1` 29 | 30 | # check enums 31 | grep >/dev/null "EnumNoItemDocs ()" $DOC_MODULE-undocumented.txt 32 | if test $? = 1 ; then failed=`expr $failed + 1`; fi 33 | tested=`expr $tested + 1` 34 | 35 | # summary 36 | successes=`expr $tested - $failed` 37 | rate=`expr 100 \* $successes / $tested`; 38 | echo "$rate %: Checks $tested, Failures: $failed" 39 | 40 | test $failed = 0 41 | exit $? 42 | -------------------------------------------------------------------------------- /tests/fail/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | SUBDIRS = . src docs 4 | 5 | if BUILD_TESTS 6 | 7 | check-local: clean 8 | 9 | endif 10 | 11 | EXTRA_DIST = meson.build 12 | 13 | -include $(top_srcdir)/git.mk 14 | -------------------------------------------------------------------------------- /tests/fail/docs/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | # We require automake 1.6 at least. 4 | AUTOMAKE_OPTIONS = 1.6 5 | 6 | # The name of the module, e.g. 'glib'. 7 | DOC_MODULE=tester 8 | 9 | # The top-level SGML file. You can change this if you want to. 10 | DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml 11 | 12 | # The directory containing the source code. Relative to $(srcdir). 13 | # gtk-doc will search all .c & .h files beneath here for inline comments 14 | # documenting the functions and macros. 15 | DOC_SOURCE_DIR=$(top_srcdir)/tests/fail/src 16 | 17 | # Extra options to pass to gtkdoc-scangobj. Not normally needed. 18 | SCANGOBJ_OPTIONS= 19 | 20 | # Extra options to supply to gtkdoc-scan. 21 | SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ 22 | --ignore-decorators="GLIB_VAR" 23 | 24 | # Extra options to supply to gtkdoc-mkdb. 25 | MKDB_OPTIONS= 26 | 27 | # Extra options to supply to gtkdoc-mkhtml 28 | MKHTML_OPTIONS= 29 | 30 | # Extra options to supply to gtkdoc-fixref. Not normally needed. 31 | # --html-dir=$(HTML_DIR) 32 | FIXXREF_OPTIONS=--extra-dir=$(glib_prefix)/share/gtk-doc/html 33 | 34 | # Used for dependencies. The docs will be rebuilt if any of these change. 35 | HFILE_GLOB=$(top_srcdir)/tests/fail/src/*.h 36 | CFILE_GLOB=$(top_srcdir)/tests/fail/src/*.c 37 | 38 | # Header files to ignore when scanning. 39 | IGNORE_HFILES=config.h 40 | 41 | # Images to copy into HTML directory. 42 | HTML_IMAGES = 43 | 44 | # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). 45 | # e.g. content_files=running.sgml building.sgml changes-2.0.sgml 46 | content_files = 47 | 48 | # SGML files where gtk-doc abbreviations (#GtkWidget) are expanded 49 | # These files must be listed here *and* in content_files 50 | # e.g. expand_content_files=running.sgml 51 | expand_content_files= 52 | 53 | # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. 54 | # Only needed if you are using gtkdoc-scangobj to dynamically query widget 55 | # signals and properties. 56 | GTKDOC_CFLAGS = -I$(top_srcdir)/tests/fail/src $(TEST_DEPS_CFLAGS) 57 | GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/fail/src/libtester.la 58 | 59 | # include generic part 60 | include $(top_srcdir)/tests/gtk-doc.make 61 | 62 | # Other files to distribute 63 | # e.g. EXTRA_DIST += version.xml.in 64 | EXTRA_DIST += 65 | 66 | CLEANFILES += \ 67 | $(DOC_MODULE)-overrides.txt 68 | 69 | if BUILD_TESTS 70 | TESTS_ENVIRONMENT = \ 71 | DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ 72 | PATH=$(abs_top_builddir):$(srcdir):$(PATH) 73 | endif 74 | 75 | EXTRA_DIST += meson.build 76 | EXTRA_DIST += xml/meson.build 77 | 78 | -include $(top_srcdir)/git.mk 79 | -------------------------------------------------------------------------------- /tests/fail/docs/meson.build: -------------------------------------------------------------------------------- 1 | fail_test_source_dir = join_paths( 2 | srcdir, 3 | 'tests', 4 | 'fail', 5 | 'src' 6 | ) 7 | 8 | fail_test_docs_dir = join_paths( 9 | srcdir, 10 | 'tests', 11 | 'fail', 12 | 'docs' 13 | ) 14 | 15 | fail_test_output_dir = join_paths( 16 | builddir, 17 | 'tests', 18 | 'fail', 19 | 'docs' 20 | ) 21 | 22 | fail_test_html_data = [] 23 | 24 | subdir('xml') 25 | 26 | test( 27 | 'test-fail-scan', 28 | python_prg, 29 | workdir: fail_test_docs_dir, 30 | is_parallel: false, 31 | args: [ 32 | gtkdoc_scan_runner_script, 33 | '--binary-dir=@0@'.format(builddir), 34 | '--change-dir=@0@'.format(fail_test_output_dir), 35 | '--module=@0@'.format('tester'), 36 | '--source-dir=@0@'.format(fail_test_source_dir), 37 | '--ignore-headers=config.h', 38 | '--deprecated-guards=GTKDOC_TESTER_DISABLE_DEPRECATED', 39 | '--ignore-decorators=GLIB_VAR', 40 | ], 41 | ) 42 | 43 | test( 44 | 'test-fail-mkdb', 45 | python_prg, 46 | workdir: fail_test_output_dir, 47 | is_parallel: false, 48 | args: [ 49 | gtkdoc_mkdb_runner_script, 50 | '--binary-dir=@0@'.format(builddir), 51 | '--module=@0@'.format('tester'), 52 | '--source-dir=@0@'.format(fail_test_source_dir), 53 | '--main-sgml-file=@0@'.format('tester-docs.xml'), 54 | '--output-format=xml', 55 | '--xml-mode', 56 | ], 57 | ) 58 | 59 | foreach style_data: gtkdoc_style_data 60 | fail_test_html_data += join_paths(srcdir, 'style', style_data) 61 | endforeach 62 | 63 | test( 64 | 'test-fail-mkhtml', 65 | python_prg, 66 | workdir: fail_test_output_dir, 67 | is_parallel: false, 68 | args: [ 69 | gtkdoc_mkhtml_runner_script, 70 | '--binary-dir=@0@'.format(builddir), 71 | '--change-dir=@0@'.format(join_paths(fail_test_output_dir, 'html')), 72 | '--html-assets=@0@'.format('@@'.join(fail_test_html_data)), 73 | '@0@'.format('tester'), 74 | '@0@'.format(join_paths('..', 'tester-docs.xml')), 75 | '--uninstalled', 76 | '--path=@0@'.format(':'.join([ 77 | fail_test_docs_dir, 78 | srcdir]) 79 | ), 80 | ], 81 | ) 82 | 83 | test( 84 | 'test-fail-fixxref', 85 | python_prg, 86 | workdir: fail_test_output_dir, 87 | is_parallel: false, 88 | args: [ 89 | gtkdoc_fixxref_runner_script, 90 | '--binary-dir=@0@'.format(builddir), 91 | '--module=@0@'.format('tester'), 92 | '--module-dir=@0@'.format('html'), 93 | '--extra-dir=@0@'.format(glib_docpath), 94 | ], 95 | ) 96 | 97 | test( 98 | 'test-fail-check', 99 | python_prg, 100 | workdir: fail_test_docs_dir, 101 | is_parallel: false, 102 | should_fail: true, 103 | args: [ 104 | gtkdoc_check_runner_script, 105 | '--binary-dir=@0@'.format(builddir), 106 | '--input-dir=@0@'.format(fail_test_docs_dir), 107 | '--output-dir=@0@'.format(fail_test_output_dir), 108 | ], 109 | ) -------------------------------------------------------------------------------- /tests/fail/docs/tester-docs.xml: -------------------------------------------------------------------------------- 1 | 2 | 6 | 7 | %gtkdocentities; 8 | ]> 9 | 10 | 11 | &package_name; Reference Manual 12 | 13 | for &package_string;. 14 | 15 | 16 | 17 | 18 | Tests 19 | 24 | 25 | 26 | 27 | 28 | API Index 29 | 30 | 31 | 32 | Index of deprecated API 33 | 34 | 35 | 36 | 37 | -------------------------------------------------------------------------------- /tests/fail/docs/tester-sections.txt: -------------------------------------------------------------------------------- 1 |
2 | tester_nodocs 3 |
4 | 5 |
6 | tester_nolongdesc 7 |
8 | 9 |
10 | tester_noshortdesc 11 |
12 | 13 |
14 | tester_brokendocs 15 | MACRO_NO_ITEM_DOCS 16 | MACRO_INCOMPLETE_DOCS 17 | MACRO_UNUSED_DOCS 18 | EnumNoItemDocs 19 | EnumIncompleteDocs 20 | EnumUnusedDocs 21 | StructNoItemDocs 22 | StructIncompleteDocs 23 | StructUnusedDocs 24 | func_no_docs 25 | func_no_item_docs 26 | func_incomplete_docs 27 | func_unused_docs 28 |
29 | 30 | -------------------------------------------------------------------------------- /tests/fail/docs/xml/meson.build: -------------------------------------------------------------------------------- 1 | configure_file( 2 | input: join_paths(srcdir, 'tests', 'gtkdocentities.ent.in'), 3 | output: 'gtkdocentities.ent', 4 | configuration: binary_in, 5 | ) 6 | -------------------------------------------------------------------------------- /tests/fail/meson.build: -------------------------------------------------------------------------------- 1 | subdir('docs') -------------------------------------------------------------------------------- /tests/fail/src/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | if BUILD_TESTS 4 | 5 | noinst_LTLIBRARIES = libtester.la 6 | 7 | libtester_la_SOURCES = tester.c tester.h 8 | #libtester_la_LIBADD = $(TEST_DEPS_LIBS) 9 | 10 | AM_CPPFLAGS = $(TEST_DEPS_CFLAGS) 11 | 12 | endif 13 | 14 | 15 | -include $(top_srcdir)/git.mk 16 | -------------------------------------------------------------------------------- /tests/fail/src/tester.c: -------------------------------------------------------------------------------- 1 | /* 2 | * SECTION:tester_nodocs 3 | * @short_description: module for gtk-doc unit test 4 | * @title: GtkdocTesterNoDocs 5 | * 6 | * This file contains non-sense code for the sole purpose of testing the docs. 7 | */ 8 | /** 9 | * SECTION:tester_nolongdesc 10 | * @short_description: module for gtk-doc unit test 11 | * @title: GtkdocTesterNoLongDesc 12 | */ 13 | /** 14 | * SECTION:tester_noshortdesc 15 | * @title: GtkdocTesterNoShortDesc 16 | * 17 | * This file contains non-sense code for the sole purpose of testing the docs. 18 | */ 19 | /** 20 | * SECTION:tester_brokendocs 21 | * @short_description: module for gtk-doc unit test 22 | * @title: GtkdocTesterBrokenDocs 23 | * 24 | * This file contains non-sense code for the sole purpose of testing the docs. 25 | */ 26 | 27 | #include "tester.h" 28 | 29 | /** 30 | * func_no_docs: 31 | */ 32 | void 33 | func_no_docs(void) 34 | { 35 | } 36 | 37 | /** 38 | * func_no_item_docs: 39 | * 40 | * Here we document the function but not the parameters. 41 | */ 42 | void 43 | func_no_item_docs(int a, char b) 44 | { 45 | } 46 | 47 | /** 48 | * func_incomplete_docs: 49 | * @a: a value 50 | * 51 | * Here we document the function but not all the parameters. 52 | */ 53 | void 54 | func_incomplete_docs(int a, char b) 55 | { 56 | } 57 | 58 | /** 59 | * func_unused_docs: 60 | * @a: a value 61 | * @b: a value 62 | * @c: an unexisting value 63 | * 64 | * Here we document the function and more than the actual parameters. 65 | */ 66 | void 67 | func_unused_docs(int a, char b) 68 | { 69 | } 70 | 71 | -------------------------------------------------------------------------------- /tests/fail/src/tester.h: -------------------------------------------------------------------------------- 1 | #ifndef GTKDOC_TESTER_H 2 | #define GTKDOC_TESTER_H 3 | 4 | #include 5 | 6 | /** 7 | * MACRO_NO_ITEM_DOCS: 8 | * 9 | * Here we document the macro but not the parameters. 10 | */ 11 | #define MACRO_NO_ITEM_DOCS(a,b) (a+b) 12 | 13 | /** 14 | * MACRO_INCOMPLETE_DOCS: 15 | * @a: a value 16 | * 17 | * Here we document the macro but not all the parameters. 18 | */ 19 | #define MACRO_INCOMPLETE_DOCS(a,b) (a+b) 20 | 21 | /** 22 | * MACRO_UNUSED_DOCS: 23 | * @a: a value 24 | * @b: a value 25 | * @c: an unexisting value 26 | * 27 | * Here we document the macro and more than the actual parameters. 28 | */ 29 | #define MACRO_UNUSED_DOCS(a,b) (a+b) 30 | 31 | 32 | /** 33 | * EnumNoItemDocs: 34 | * 35 | * Here we document the enum but not the values. 36 | * http://bugzilla.gnome.org/show_bug.cgi?id=568711 37 | */ 38 | typedef enum { 39 | ENUM_NO_ITEM_DOCS_1, 40 | ENUM_NO_ITEM_DOCS_2 41 | } EnumNoItemDocs; 42 | 43 | /** 44 | * EnumIncompleteDocs: 45 | * @ENUM_INCOMPLETE_DOCS_1: a value 46 | * 47 | * Here we document the enum but not all the values. 48 | */ 49 | typedef enum { 50 | ENUM_INCOMPLETE_DOCS_1, 51 | ENUM_INCOMPLETE_DOCS_2 52 | } EnumIncompleteDocs; 53 | 54 | /** 55 | * EnumUnusedDocs: 56 | * @ENUM_UNUSED_DOCS_1: a value 57 | * @ENUM_UNUSED_DOCS_2: a value 58 | * @ENUM_UNUSED_DOCS_3: an unexisting value 59 | * 60 | * Here we document the enum and more than the actual values. 61 | */ 62 | typedef enum { 63 | ENUM_UNUSED_DOCS_1, 64 | ENUM_UNUSED_DOCS_2 65 | } EnumUnusedDocs; 66 | 67 | 68 | /** 69 | * StructNoItemDocs: 70 | * 71 | * Here we document the struct but not the values. 72 | */ 73 | typedef struct { 74 | int a; 75 | char b; 76 | } StructNoItemDocs; 77 | 78 | /** 79 | * StructIncompleteDocs: 80 | * @a: a value 81 | * 82 | * Here we document the struct but not all the values. 83 | */ 84 | typedef struct { 85 | int a; 86 | char b; 87 | } StructIncompleteDocs; 88 | 89 | /** 90 | * StructUnusedDocs: 91 | * @a: a value 92 | * @b: a value 93 | * @c: an unexisting value 94 | * 95 | * Here we document the struct and more than the actual values. 96 | */ 97 | typedef struct { 98 | int a; 99 | char b; 100 | } StructUnusedDocs; 101 | 102 | 103 | void func_no_docs(void); 104 | void func_no_item_docs(int a, char b); 105 | void func_incomplete_docs(int a, char b); 106 | void func_unused_docs(int a, char b); 107 | 108 | #endif // GTKDOC_TESTER_H 109 | 110 | -------------------------------------------------------------------------------- /tests/gobject.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -e 4 | 5 | gtkdoctest.sh gobject 6 | sanity.sh gobject 7 | -------------------------------------------------------------------------------- /tests/gobject/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | SUBDIRS = . src docs 4 | 5 | if BUILD_TESTS 6 | 7 | check-local: clean 8 | 9 | endif 10 | 11 | EXTRA_DIST = \ 12 | examples/gobject.c \ 13 | meson.build 14 | 15 | -include $(top_srcdir)/git.mk 16 | -------------------------------------------------------------------------------- /tests/gobject/docs/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | # We require automake 1.6 at least. 4 | AUTOMAKE_OPTIONS = 1.6 5 | 6 | # The name of the module, e.g. 'glib'. 7 | DOC_MODULE=tester 8 | 9 | # The top-level SGML file. You can change this if you want to. 10 | DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml 11 | 12 | # The directory containing the source code. Relative to $(srcdir). 13 | # gtk-doc will search all .c & .h files beneath here for inline comments 14 | # documenting the functions and macros. 15 | DOC_SOURCE_DIR=$(top_srcdir)/tests/gobject/src 16 | 17 | # Extra options to pass to gtkdoc-scangobj. Not normally needed. 18 | SCANGOBJ_OPTIONS= 19 | 20 | # Extra options to supply to gtkdoc-scan. 21 | SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ 22 | --rebuild-types 23 | 24 | # Extra options to supply to gtkdoc-mkdb. 25 | MKDB_OPTIONS=--xml-mode 26 | 27 | # Extra options to supply to gtkdoc-mkhtml 28 | MKHTML_OPTIONS=--path=$(abs_top_srcdir)/tests/gobject/examples 29 | 30 | # Extra options to supply to gtkdoc-mkpdf 31 | MKPDF_OPTIONS=--path=$(abs_top_srcdir)/tests/gobject/examples 32 | 33 | # Extra options to supply to gtkdoc-fixref. Not normally needed. 34 | # --html-dir=$(HTML_DIR) 35 | FIXXREF_OPTIONS=--extra-dir=$(glib_prefix)/share/gtk-doc/html 36 | 37 | # Used for dependencies. The docs will be rebuilt if any of these change. 38 | HFILE_GLOB=$(top_srcdir)/tests/gobject/src/*.h 39 | CFILE_GLOB=$(top_srcdir)/tests/gobject/src/*.c 40 | 41 | # Header files to ignore when scanning. 42 | IGNORE_HFILES=config.h 43 | 44 | # Images to copy into HTML directory. 45 | HTML_IMAGES = \ 46 | $(srcdir)/images/object.png 47 | 48 | # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). 49 | # e.g. content_files=running.sgml building.sgml changes-2.0.sgml 50 | content_files = 51 | 52 | # SGML files where gtk-doc abbreviations (#GtkWidget) are expanded 53 | # These files must be listed here *and* in content_files 54 | # e.g. expand_content_files=running.sgml 55 | expand_content_files= 56 | 57 | # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. 58 | # Only needed if you are using gtkdoc-scangobj to dynamically query widget 59 | # signals and properties. 60 | GTKDOC_CFLAGS = -I$(top_srcdir)/tests/gobject/src $(TEST_DEPS_CFLAGS) 61 | GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/gobject/src/libtester.la 62 | 63 | # include generic part 64 | include $(top_srcdir)/tests/gtk-doc.make 65 | 66 | # Other files to distribute 67 | # e.g. EXTRA_DIST += version.xml.in 68 | EXTRA_DIST += tester.types 69 | 70 | CLEANFILES += \ 71 | $(DOC_MODULE)-overrides.txt \ 72 | $(DOC_MODULE).types 73 | 74 | if BUILD_TESTS 75 | TESTS_ENVIRONMENT = \ 76 | DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ 77 | PATH=$(abs_top_builddir):$(srcdir):$(PATH) 78 | endif 79 | 80 | EXTRA_DIST += meson.build 81 | EXTRA_DIST += images/meson.build 82 | EXTRA_DIST += xml/meson.build 83 | 84 | -include $(top_srcdir)/git.mk 85 | -------------------------------------------------------------------------------- /tests/gobject/docs/images/meson.build: -------------------------------------------------------------------------------- 1 | gobject_test_html_data += [ 2 | join_paths(srcdir, 'tests', 'gobject', 'docs', 'images', 'object.png') 3 | ] -------------------------------------------------------------------------------- /tests/gobject/docs/images/object.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GNOME/gtk-doc/6fafd62a12a86b774c3a48c00ee2c7bda1459ce4/tests/gobject/docs/images/object.png -------------------------------------------------------------------------------- /tests/gobject/docs/meson.build: -------------------------------------------------------------------------------- 1 | gobject_test_source_dir = join_paths( 2 | srcdir, 3 | 'tests', 4 | 'gobject', 5 | 'src' 6 | ) 7 | 8 | gobject_test_docs_dir = join_paths( 9 | srcdir, 10 | 'tests', 11 | 'gobject', 12 | 'docs' 13 | ) 14 | 15 | gobject_test_output_dir = join_paths( 16 | builddir, 17 | 'tests', 18 | 'gobject', 19 | 'docs' 20 | ) 21 | 22 | gobject_test_html_data = [] 23 | 24 | subdir('xml') 25 | 26 | fs.copyfile(join_paths(gobject_test_docs_dir, 'tester-sections.txt')) 27 | 28 | test( 29 | 'test-gobject-scan', 30 | python_prg, 31 | workdir: gobject_test_docs_dir, 32 | is_parallel: false, 33 | args: [ 34 | gtkdoc_scan_runner_script, 35 | '--binary-dir=@0@'.format(builddir), 36 | '--change-dir=@0@'.format(gobject_test_output_dir), 37 | '--module=@0@'.format('tester'), 38 | '--source-dir=@0@'.format(gobject_test_source_dir), 39 | '--ignore-headers=config.h', 40 | '--deprecated-guards=GTKDOC_TESTER_DISABLE_DEPRECATED', 41 | '--rebuild-types', 42 | ], 43 | ) 44 | 45 | sanitizer_args = [] 46 | 47 | if get_option('b_sanitize') == 'address' or get_option('b_sanitize') == 'address,undefined' 48 | sanitizer_args += [ 49 | '--extra-cflags=-fsanitize=address', 50 | '--ldflags=-fsanitize=address', 51 | ] 52 | endif 53 | 54 | if get_option('b_sanitize') == 'undefined' or get_option('b_sanitize') == 'address,undefined' 55 | sanitizer_args += [ 56 | '--extra-cflags=-fsanitize=undefined', 57 | '--ldflags=-fsanitize=undefined', 58 | ] 59 | endif 60 | 61 | test( 62 | 'test-gobject-scangobj', 63 | python_prg, 64 | workdir: gobject_test_output_dir, 65 | is_parallel: false, 66 | args: [ 67 | gtkdoc_scangobj_runner_script, 68 | '--binary-dir=@0@'.format(builddir), 69 | '--pkg-config=@0@'.format(pkgconfig_prg_path), 70 | '--extra-pkg=@0@'.format('glib-2.0'), 71 | '--extra-pkg=@0@'.format('gobject-2.0'), 72 | '--extra-lib=@0@'.format(gobject_test_lib.full_path()), 73 | '--module=@0@'.format('tester'), 74 | ] + sanitizer_args, 75 | env: [ 76 | 'ASAN_OPTIONS=detect_leaks=0', 77 | ], 78 | ) 79 | 80 | test( 81 | 'test-gobject-mkdb', 82 | python_prg, 83 | workdir: gobject_test_output_dir, 84 | is_parallel: false, 85 | args: [ 86 | gtkdoc_mkdb_runner_script, 87 | '--binary-dir=@0@'.format(builddir), 88 | '--module=@0@'.format('tester'), 89 | '--source-dir=@0@'.format(gobject_test_source_dir), 90 | '--main-sgml-file=@0@'.format('tester-docs.xml'), 91 | '--output-format=xml', 92 | '--xml-mode', 93 | ], 94 | ) 95 | 96 | foreach style_data: gtkdoc_style_data 97 | gobject_test_html_data += join_paths(srcdir, 'style', style_data) 98 | endforeach 99 | 100 | subdir('images') # Appends to gobject_test_html_data 101 | 102 | test( 103 | 'test-gobject-mkhtml', 104 | python_prg, 105 | workdir: gobject_test_output_dir, 106 | is_parallel: false, 107 | args: [ 108 | gtkdoc_mkhtml_runner_script, 109 | '--binary-dir=@0@'.format(builddir), 110 | '--change-dir=@0@'.format(join_paths(gobject_test_output_dir, 'html')), 111 | '--html-assets=@0@'.format('@@'.join(gobject_test_html_data)), 112 | '@0@'.format('tester'), 113 | '@0@'.format(join_paths('..', 'tester-docs.xml')), 114 | '--uninstalled', 115 | '--path=@0@'.format(':'.join([ 116 | gobject_test_docs_dir, 117 | srcdir, 118 | ]) 119 | ), 120 | ], 121 | ) 122 | 123 | test( 124 | 'test-gobject-fixxref', 125 | python_prg, 126 | workdir: gobject_test_output_dir, 127 | is_parallel: false, 128 | args: [ 129 | gtkdoc_fixxref_runner_script, 130 | '--binary-dir=@0@'.format(builddir), 131 | '--module=@0@'.format('tester'), 132 | '--module-dir=@0@'.format('html'), 133 | '--extra-dir=@0@'.format(glib_docpath), 134 | '--extra-dir=@0@'.format(gobject_docpath), 135 | ], 136 | ) 137 | 138 | test( 139 | 'test-gobject-check', 140 | python_prg, 141 | workdir: gobject_test_docs_dir, 142 | is_parallel: false, 143 | args: [ 144 | gtkdoc_check_runner_script, 145 | '--binary-dir=@0@'.format(builddir), 146 | '--input-dir=@0@'.format(gobject_test_docs_dir), 147 | '--output-dir=@0@'.format(gobject_test_output_dir), 148 | ], 149 | ) 150 | -------------------------------------------------------------------------------- /tests/gobject/docs/tester-docs.xml: -------------------------------------------------------------------------------- 1 | 2 | 6 | 7 | %gtkdocentities; 8 | ]> 9 | 10 | 11 | &package_name; Reference Manual 12 | 13 | The gtk-doc team. 14 | 15 | 16 | for &package_string;. 17 | The latest version of this documentation can be found on-line at 18 | http://[SERVER]/tester/. 19 | 20 | 21 | 22 | This manual is published as public domain. 23 | 24 | 25 | 26 | 27 | 28 | Introduction 29 | 30 | This document is for testing purpose only. 31 | It is generated from Docbook-XML. 32 | 33 | 34 | Most of the actual text is quite non-sense. Don't pay attention. 35 | 36 | 37 | 38 | 39 | 40 | 41 | Overview 42 | 43 | How to build the library 44 | 45 | 46 | 47 | 48 | 49 | API Reference 50 | 51 | Tests 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | Appendix 63 | 64 | 65 | Object Hierarchy 66 | 67 | 68 | 69 | 70 | Object Index 71 | 72 | 73 | 74 | 75 | API Index 76 | 77 | 78 | 79 | Index of deprecated API 80 | 81 | 82 | 83 | Index of new API in 0.1 84 | 85 | 86 | 87 | Index of new API in 0.5 88 | 89 | 90 | 91 | 92 | Glossary 93 | A 94 | 95 | API 96 | 97 | Application Programming Interface 98 | 99 | 100 | 101 | X 102 | 103 | XML 104 | 105 | Extensible Markup Language 106 | 107 | 108 | 109 | XSL 110 | 111 | XML Stylesheet Language 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | -------------------------------------------------------------------------------- /tests/gobject/docs/tester-sections.txt: -------------------------------------------------------------------------------- 1 |
2 | object 3 | GtkdocObject 4 | GtkdocObjectClass 5 | gtkdoc_object_new 6 | gtkdoc_object_set_otest 7 | gtkdoc_object_frobnicate 8 | gtkdoc_object_fooify 9 | gtkdoc_object_do_not_use 10 | GTKDOC_OBJECT_MACRO_DUMMY 11 | GTKDOC_OBJECT_MACRO_SUM 12 | 13 | GTKDOC_OBJECT 14 | GTKDOC_IS_OBJECT 15 | GTKDOC_TYPE_OBJECT 16 | gtkdoc_object_get_type 17 | GTKDOC_OBJECT_CLASS 18 | GTKDOC_IS_OBJECT_CLASS 19 | GTKDOC_OBJECT_GET_CLASS 20 |
21 | 22 |
23 | object2 24 | GtkdocObject2 25 | GtkdocObject2Class 26 | 27 | GTKDOC_TYPE_OBJECT2 28 | gtkdoc_object2_get_type 29 |
30 | 31 |
32 | object3 33 | 34 | GtkdocObject3 35 | GtkdocObject3Class 36 | GTKDOC_TYPE_OBJECT3 37 | gtkdoc_object3_get_type 38 |
39 | 40 |
41 | iface 42 | GtkdocIface 43 | GtkdocIfaceInterface 44 | gtkdoc_iface_configure 45 | GTKDOC_IFACE_MACRO_DUMMY 46 | GTKDOC_IFACE_MACRO_SUM 47 | 48 | GTKDOC_IFACE 49 | GTKDOC_IS_IFACE 50 | GTKDOC_TYPE_IFACE 51 | gtkdoc_iface_get_type 52 | GTKDOC_IFACE_GET_INTERFACE 53 |
54 | 55 |
56 | iface2 57 | GtkdocIface2 58 | 59 | GTKDOC_TYPE_IFACE2 60 | gtkdoc_iface2_get_type 61 |
62 | 63 |
64 | types 65 | GtkdocEnum 66 | GtkdocEnum2 67 | GtkdocPlainOldData 68 | GtkdocBoxedPlainOldData 69 | GtkdocHelperEnum 70 | GtkdocHelperStruct 71 | 72 | GTKDOC_TYPE_ENUM 73 | GTKDOC_TYPE_ENUM2 74 | GTKDOC_TYPE_BOXED 75 | gtkdoc_enum_get_type 76 | gtkdoc_enum2_get_type 77 | gtkdoc_boxed_get_type 78 | GTKDOC_TYPE_BOXED_PLAIN_OLD_DATA 79 | gtkdoc_boxed_plain_old_data_get_type 80 |
81 | 82 | -------------------------------------------------------------------------------- /tests/gobject/docs/xml/meson.build: -------------------------------------------------------------------------------- 1 | configure_file( 2 | input: join_paths(srcdir, 'tests', 'gtkdocentities.ent.in'), 3 | output: 'gtkdocentities.ent', 4 | configuration: binary_in, 5 | ) 6 | -------------------------------------------------------------------------------- /tests/gobject/examples/gobject.c: -------------------------------------------------------------------------------- 1 | /* example for gobject usage 2 | * checkout the article at http://en.wikipedia.org/wiki/GObject 3 | * 4 | * This example is part of the release, that can be downloaded 5 | * from ftp://ftp.gnome.org/pub/gnome/sources/gtk-doc/ or any mirror. 6 | */ 7 | 8 | #include 9 | #include 10 | 11 | gint 12 | main(gint argc, gchar **argv) 13 | { 14 | GObject *myobj; 15 | 16 | myobj = gtkdoc_object_new(); 17 | g_object_set (myobj, "parameter", 5, NULL); 18 | g_object_unref (myobj); 19 | 20 | return 0; 21 | } 22 | -------------------------------------------------------------------------------- /tests/gobject/meson.build: -------------------------------------------------------------------------------- 1 | subdir('src') 2 | subdir('docs') 3 | -------------------------------------------------------------------------------- /tests/gobject/src/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | if BUILD_TESTS 4 | 5 | noinst_LTLIBRARIES = libtester.la 6 | 7 | libtester_la_SOURCES = \ 8 | gobject.c gobject.h \ 9 | giface.c giface.h \ 10 | gtypes.c gtypes.h 11 | #libtester_la_LIBADD = $(TEST_DEPS_LIBS) 12 | 13 | AM_CPPFLAGS = $(TEST_DEPS_CFLAGS) 14 | 15 | endif 16 | 17 | EXTRA_DIST = meson.build 18 | 19 | -include $(top_srcdir)/git.mk 20 | -------------------------------------------------------------------------------- /tests/gobject/src/giface.c: -------------------------------------------------------------------------------- 1 | /** 2 | * SECTION:iface 3 | * @title: GtkdocIface 4 | * @short_description: interface for gtk-doc unit test 5 | * @see_also: #GtkdocObject 6 | * 7 | * This file contains non-sense code for the sole purpose of testing the docs. 8 | * We can link to the #GtkdocIface:itest property and the #GtkdocIface::itest 9 | * signal. 10 | * An instance can be configured using the gtkdoc_iface_configure() function. 11 | * 12 | * I can haz pictures too! 13 | * 14 | * 15 | * Home sweet home. 16 | * 17 | * 18 | * Just in case you wonder, special characters can be escaped with a \ like 19 | * in \% or \# or even \@. 20 | * 21 | * We also support verbatim spans - lets test escaping of a `` block. 22 | */ 23 | /** 24 | * SECTION:iface2 25 | * @title: GtkdocIface2 26 | * @short_description: interface with a prerequisite for gtk-doc unit test 27 | * @see_also: #GtkdocObject, #GtkdocIface 28 | * 29 | * This file contains non-sense code for the sole purpose of testing the docs. 30 | */ 31 | 32 | #include "giface.h" 33 | 34 | /* constructor methods */ 35 | 36 | /* methods */ 37 | 38 | /** 39 | * gtkdoc_iface_configure: 40 | * @config: settings 41 | * 42 | * Configure a new instance 43 | * 44 | * Returns: %TRUE for success or %FALSE in case of an error 45 | * 46 | * Since: 0.1 47 | */ 48 | gboolean gtkdoc_iface_configure (gchar *config) { 49 | return(TRUE); 50 | } 51 | 52 | /* class internals */ 53 | 54 | static void gtkdoc_iface_base_init (gpointer g_class) { 55 | static gboolean initialized = FALSE; 56 | 57 | if (!initialized) { 58 | /** 59 | * GtkdocIface::itest: 60 | * @self: myself 61 | * 62 | * The event has been triggered. 63 | */ 64 | g_signal_new ("itest", G_TYPE_FROM_CLASS (g_class), 65 | G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS, 66 | G_STRUCT_OFFSET (GtkdocIfaceInterface,test), 67 | NULL, // accumulator 68 | NULL, // acc data 69 | g_cclosure_marshal_VOID__OBJECT, 70 | G_TYPE_NONE, // return type 71 | 0); // n_params 72 | 73 | g_object_interface_install_property (g_class , 74 | g_param_spec_string ("itest", 75 | "itest prop", 76 | "dummy property for iface", 77 | "dummy", /* default value */ 78 | G_PARAM_READWRITE)); 79 | initialized = TRUE; 80 | } 81 | } 82 | 83 | GType gtkdoc_iface_get_type (void) { 84 | static GType type = 0; 85 | if (type == 0) { 86 | static const GTypeInfo info = { 87 | (guint16)sizeof(GtkdocIfaceInterface), 88 | gtkdoc_iface_base_init, // base_init 89 | NULL, // base_finalize 90 | NULL, // class_init 91 | NULL, // class_finalize 92 | NULL, // class_data 93 | 0, 94 | 0, // n_preallocs 95 | NULL, // instance_init 96 | NULL // value_table 97 | }; 98 | type = g_type_register_static(G_TYPE_INTERFACE,"GtkdocIface",&info,0); 99 | } 100 | return type; 101 | } 102 | 103 | GType gtkdoc_iface2_get_type (void) { 104 | static GType type = 0; 105 | if (type == 0) { 106 | static const GTypeInfo info = { 107 | (guint16)sizeof(GtkdocIfaceInterface), 108 | NULL, // base_init 109 | NULL, // base_finalize 110 | NULL, // class_init 111 | NULL, // class_finalize 112 | NULL, // class_data 113 | 0, 114 | 0, // n_preallocs 115 | NULL, // instance_init 116 | NULL // value_table 117 | }; 118 | type = g_type_register_static(G_TYPE_INTERFACE,"GtkdocIface2",&info,0); 119 | g_type_interface_add_prerequisite(type, GTKDOC_TYPE_IFACE); 120 | } 121 | return type; 122 | } 123 | 124 | -------------------------------------------------------------------------------- /tests/gobject/src/giface.h: -------------------------------------------------------------------------------- 1 | #ifndef GTKDOC_IFACE_H 2 | #define GTKDOC_IFACE_H 3 | 4 | #include 5 | #include 6 | 7 | /* type macros */ 8 | 9 | #define GTKDOC_TYPE_IFACE (gtkdoc_iface_get_type ()) 10 | #define GTKDOC_IFACE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTKDOC_TYPE_IFACE, GtkdocIface)) 11 | #define GTKDOC_IS_IFACE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTKDOC_TYPE_IFACE)) 12 | #define GTKDOC_IFACE_GET_INTERFACE(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GTKDOC_TYPE_IFACE, GtkdocIfaceInterface)) 13 | 14 | #define GTKDOC_TYPE_IFACE2 (gtkdoc_iface2_get_type ()) 15 | 16 | /* type structs */ 17 | 18 | /** 19 | * GtkdocIface: 20 | * 21 | * opaque instance of gtk-doc unit test interface 22 | */ 23 | typedef struct _GtkdocIface GtkdocIface; 24 | typedef struct _GtkdocIfaceInterface GtkdocIfaceInterface; 25 | 26 | /** 27 | * GtkdocIface2: 28 | * 29 | * opaque instance of gtk-doc unit test interface 30 | */ 31 | typedef struct _GtkdocIface2 GtkdocIface2; 32 | 33 | /** 34 | * GtkdocIfaceInterface: 35 | * @parent: this is a bug :/ 36 | * @test: overideable method 37 | * 38 | * class data of gtk-doc unit test interface 39 | */ 40 | struct _GtkdocIfaceInterface { 41 | GTypeInterface parent; 42 | 43 | /* class methods */ 44 | void (*test)(const GtkdocIface * const self, gconstpointer const user_data); 45 | }; 46 | 47 | GType gtkdoc_iface_get_type(void) G_GNUC_CONST; 48 | GType gtkdoc_iface2_get_type(void) G_GNUC_CONST; 49 | 50 | gboolean gtkdoc_iface_configure (gchar *config); 51 | 52 | /** 53 | * GTKDOC_IFACE_MACRO_DUMMY: 54 | * @parameter_1: first arg 55 | * @parameter_2: second arg 56 | * 57 | * This macro does nothing. 58 | */ 59 | #define GTKDOC_IFACE_MACRO_DUMMY(parameter_1,parameter_2) /* do nothing */ 60 | 61 | /** 62 | * GTKDOC_IFACE_MACRO_SUM: 63 | * @parameter_1: first arg 64 | * @parameter_2: second arg 65 | * 66 | * This macro adds its args. 67 | * 68 | * Returns: the sum of @parameter_1 and @parameter_2 69 | */ 70 | #define GTKDOC_IFACE_MACRO_SUM(parameter_1,parameter_2) \ 71 | ((parameter_1) + (parameter_2)) 72 | 73 | #define _GTKDOC_IFACE_INTERNAL_MACRO /* do nothing */ 74 | 75 | #endif // GTKDOC_IFACE_H 76 | 77 | -------------------------------------------------------------------------------- /tests/gobject/src/gobject.h: -------------------------------------------------------------------------------- 1 | #ifndef GTKDOC_OBJECT_H 2 | #define GTKDOC_OBJECT_H 3 | 4 | #include 5 | #include 6 | 7 | /* type macros */ 8 | 9 | #define GTKDOC_TYPE_OBJECT (gtkdoc_object_get_type ()) 10 | #define GTKDOC_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTKDOC_TYPE_OBJECT, GtkdocObject)) 11 | #define GTKDOC_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GTKDOCTYPE_OBJECT, GtkdocObjectClass)) 12 | #define GTKDOC_IS_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTKDOC_TYPE_OBJECT)) 13 | #define GTKDOC_IS_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GTKDOC_TYPE_OBJECT)) 14 | #define GTKDOC_OBJECT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GTKDOC_TYPE_OBJECT, GtkdocObjectClass)) 15 | 16 | #define GTKDOC_TYPE_OBJECT2 (gtkdoc_object2_get_type ()) 17 | 18 | #define GTKDOC_TYPE_OBJECT3 (gtkdoc_object3_get_type ()) 19 | 20 | /* type structs */ 21 | 22 | typedef struct _GtkdocObject GtkdocObject; 23 | typedef struct _GtkdocObjectClass GtkdocObjectClass; 24 | 25 | typedef struct _GtkdocObject2 GtkdocObject2; 26 | typedef struct _GtkdocObject2Class GtkdocObject2Class; 27 | 28 | typedef struct _GtkdocObject3 GtkdocObject3; 29 | typedef struct _GtkdocObject3Class GtkdocObject3Class; 30 | 31 | /* in gtkdoc-scan::ScanHeader() we currently skip the enums, but output a decl 32 | * to -decl.txt and -decl-list.txt for the struct 33 | * If the symbol has no docs, we get a warning in -unused.txt for the struct, but 34 | * not the enum 35 | * 36 | typedef struct GtkdocHelperStruct GtkdocHelperStruct; 37 | typedef enum GtkdocHelperEnum GtkdocHelperEnum; 38 | */ 39 | 40 | /** 41 | * GtkdocObject: 42 | * 43 | * instance data of gtk-doc unit test class 44 | */ 45 | struct _GtkdocObject { 46 | GObject parent; 47 | 48 | /*< private >*/ 49 | gchar *test_string; 50 | }; 51 | 52 | /** 53 | * GtkdocObjectClass: 54 | * @parent: this is a bug :/ 55 | * @test: overideable method 56 | * @ping: can be used before calling the @test() function 57 | * @foo_bar: lets you refine your frobnicator 58 | * 59 | * class data of gtk-doc unit test class 60 | */ 61 | struct _GtkdocObjectClass { 62 | GObjectClass parent; 63 | 64 | /* class methods */ 65 | void (*test)(const GtkdocObject * const self, gconstpointer const user_data); 66 | gboolean (*ping)(const GtkdocObject * const self); 67 | gboolean (*foo_bar)(const GtkdocObject * const self); 68 | }; 69 | 70 | /** 71 | * GtkdocObject2: 72 | * 73 | * instance data of gtk-doc unit test class 74 | */ 75 | struct _GtkdocObject2 { 76 | GObject parent; 77 | }; 78 | 79 | /** 80 | * GtkdocObject2Class: 81 | * @parent: this is a bug :/ 82 | * 83 | * class data of gtk-doc unit test class 84 | */ 85 | struct _GtkdocObject2Class { 86 | GObjectClass parent; 87 | }; 88 | 89 | struct _GtkdocObject3 { 90 | GObject parent; 91 | }; 92 | 93 | struct _GtkdocObject3Class { 94 | GObjectClass parent; 95 | }; 96 | 97 | 98 | /** 99 | * GtkdocHelperStruct: 100 | * @a: field 101 | * 102 | * GtkdocHelperStruct 103 | */ 104 | struct GtkdocHelperStruct { 105 | int a; 106 | }; 107 | 108 | /** 109 | * GtkdocHelperEnum: 110 | * @GTKDOC_HELPER_ENUM_A: enum a 111 | * @GTKDOC_HELPER_ENUM_B: enum b 112 | * 113 | * GtkdocHelperEnum 114 | */ 115 | enum GtkdocHelperEnum { 116 | GTKDOC_HELPER_ENUM_A, 117 | GTKDOC_HELPER_ENUM_B 118 | }; 119 | 120 | GType gtkdoc_object_get_type(void) G_GNUC_CONST; 121 | GType gtkdoc_object2_get_type(void) G_GNUC_CONST; 122 | GType gtkdoc_object3_get_type(void) G_GNUC_CONST; 123 | 124 | GtkdocObject *gtkdoc_object_new(void); 125 | #ifndef GTKDOC_TESTER_DISABLE_DEPRECATED 126 | void gtkdoc_object_set_otest (GObject *self, const gchar *value); 127 | void gtkdoc_object_do_not_use (GObject *self); 128 | #endif 129 | void gtkdoc_object_frobnicate (GObject *self, gint n); 130 | gboolean gtkdoc_object_fooify (GObject *self, ...); 131 | 132 | /** 133 | * GTKDOC_OBJECT_MACRO_DUMMY: 134 | * @parameter_1: first arg 135 | * @parameter_2: second arg 136 | * 137 | * This macro does nothing. 138 | * 139 | * Since: 0.1 140 | */ 141 | #define GTKDOC_OBJECT_MACRO_DUMMY(parameter_1,parameter_2) /* do nothing */ 142 | 143 | /** 144 | * GTKDOC_OBJECT_MACRO_SUM: 145 | * @parameter_1: first arg 146 | * @parameter_2: second arg 147 | * 148 | * This macro adds its args. 149 | * 150 | * Returns: the sum of @parameter_1 and @parameter_2 151 | */ 152 | #define GTKDOC_OBJECT_MACRO_SUM(parameter_1,parameter_2) \ 153 | ((parameter_1) + (parameter_2)) 154 | 155 | #define _GTKDOC_OBJECT_INTERNAL_MACRO /* do nothing */ 156 | 157 | #endif // GTKDOC_OBJECT_H 158 | 159 | -------------------------------------------------------------------------------- /tests/gobject/src/gtypes.c: -------------------------------------------------------------------------------- 1 | /** 2 | * SECTION:types 3 | * @title: GtkdocTypes 4 | * @short_description: other gobject types for gtk-doc unit test 5 | * @see_also: #GtkdocObject, #GtkdocIface 6 | * 7 | * This file contains non-sense code for the sole purpose of testing the docs. 8 | */ 9 | 10 | #include "gtypes.h" 11 | 12 | /* enum: class internals */ 13 | 14 | GType gtkdoc_enum_get_type (void) { 15 | static GType type = 0; 16 | if(type==0) { 17 | static const GEnumValue values[] = { 18 | { GTKDOC_ENUM_V1, "GTKDOC_ENUM_V1", "first" }, 19 | { GTKDOC_ENUM_V2, "GTKDOC_ENUM_V2", "second" }, 20 | { GTKDOC_ENUM_V3, "GTKDOC_ENUM_V3", "third" }, 21 | { 0, NULL, NULL}, 22 | }; 23 | type = g_enum_register_static ("GtkdocEnum", values); 24 | } 25 | return type; 26 | } 27 | 28 | GType gtkdoc_enum2_get_type (void) { 29 | static GType type = 0; 30 | if(type==0) { 31 | static const GEnumValue values[] = { 32 | { GTKDOC_ENUM2_V1, "GTKDOC_ENUM2_V1", "first" }, 33 | { GTKDOC_ENUM2_V2, "GTKDOC_ENUM2_V2", "second" }, 34 | { 0, NULL, NULL}, 35 | }; 36 | type = g_enum_register_static ("GtkdocEnum2", values); 37 | } 38 | return type; 39 | } 40 | 41 | /* boxed: class internals */ 42 | 43 | static gpointer gtkdoc_boxed_copy (gpointer boxed) { 44 | return boxed; 45 | } 46 | 47 | static void gtkdoc_boxed_free (gpointer boxed) { 48 | } 49 | 50 | GType gtkdoc_boxed_get_type (void) { 51 | static GType type = 0; 52 | if (type == 0) { 53 | type = g_boxed_type_register_static("GtkdocBoxed", 54 | (GBoxedCopyFunc) gtkdoc_boxed_copy, (GBoxedFreeFunc) gtkdoc_boxed_free); 55 | } 56 | return type; 57 | } 58 | 59 | /* boxed plain old data: class internals */ 60 | 61 | static gpointer gtkdoc_boxed_plain_old_data_copy (gpointer boxed) { 62 | return g_memdup2(boxed, sizeof(GtkdocBoxedPlainOldData)); 63 | } 64 | 65 | static void gtkdoc_boxed_plain_old_data_free (gpointer boxed) { 66 | g_free(boxed); 67 | } 68 | 69 | GType gtkdoc_boxed_plain_old_data_get_type (void) { 70 | static GType type = 0; 71 | if (type == 0) { 72 | type = g_boxed_type_register_static("GtkdocBoxedPlainOldData", 73 | (GBoxedCopyFunc) gtkdoc_boxed_plain_old_data_copy, 74 | (GBoxedFreeFunc) gtkdoc_boxed_plain_old_data_free); 75 | } 76 | return type; 77 | } 78 | -------------------------------------------------------------------------------- /tests/gobject/src/gtypes.h: -------------------------------------------------------------------------------- 1 | #ifndef GTKDOC_TYPES_H 2 | #define GTKDOC_TYPES_H 3 | 4 | #include 5 | #include 6 | 7 | /* type macros */ 8 | 9 | #define GTKDOC_TYPE_ENUM (gtkdoc_enum_get_type ()) 10 | #define GTKDOC_TYPE_ENUM2 (gtkdoc_enum2_get_type ()) 11 | #define GTKDOC_TYPE_BOXED (gtkdoc_boxed_get_type ()) 12 | 13 | /** 14 | * GtkdocEnum: 15 | * @GTKDOC_ENUM_V1: first 16 | * @GTKDOC_ENUM_V2: second 17 | * Since: 0.5 18 | * 19 | * Enum values for the #GtkdocEnum type. 20 | */ 21 | typedef enum { 22 | GTKDOC_ENUM_V1=0, 23 | GTKDOC_ENUM_V2, 24 | /*< private >*/ 25 | GTKDOC_ENUM_V3 26 | } GtkdocEnum; 27 | 28 | /** 29 | * GtkdocEnum2: 30 | * @GTKDOC_ENUM2_V1: first 31 | * @GTKDOC_ENUM2_V2: second 32 | * 33 | * Enum values for the #GtkdocEnum2 type. 34 | */ 35 | typedef enum { 36 | GTKDOC_ENUM2_V1=0, 37 | GTKDOC_ENUM2_V2, 38 | } GtkdocEnum2; 39 | 40 | GType gtkdoc_enum_get_type(void) G_GNUC_CONST; 41 | GType gtkdoc_enum2_get_type(void) G_GNUC_CONST; 42 | GType gtkdoc_boxed_get_type(void) G_GNUC_CONST; 43 | 44 | 45 | /** 46 | * GtkdocPlainOldData: 47 | * @n: Some integer member. 48 | * @x: Some floating point member. 49 | * 50 | * Unboxed plain old data that should default to public members. 51 | **/ 52 | typedef struct { 53 | guint n; 54 | gdouble x; 55 | /**/ 56 | gpointer priv; 57 | } GtkdocPlainOldData; 58 | 59 | #define GTKDOC_TYPE_BOXED_PLAIN_OLD_DATA (gtkdoc_boxed_plain_old_data_get_type ()) 60 | 61 | /** 62 | * GtkdocBoxedPlainOldData: 63 | * @n: Some integer member. 64 | * @x: Some floating point member. 65 | * 66 | * Boxed plain old data that should default to public members. 67 | **/ 68 | typedef struct { 69 | guint n; 70 | gdouble x; 71 | /**/ 72 | gpointer priv; 73 | } GtkdocBoxedPlainOldData; 74 | 75 | GType gtkdoc_boxed_plain_old_data_get_type(void) G_GNUC_CONST; 76 | 77 | #endif // GTKDOC_TYPES_H 78 | 79 | -------------------------------------------------------------------------------- /tests/gobject/src/meson.build: -------------------------------------------------------------------------------- 1 | gobject_test_public_h = [ 2 | 'giface.h', 3 | 'gobject.h', 4 | 'gtypes.h', 5 | ] 6 | 7 | gobject_test_c = [ 8 | 'giface.c', 9 | 'gobject.c', 10 | 'gtypes.c', 11 | ] 12 | 13 | gobject_test_deps = [ 14 | glib_dep, 15 | gobject_dep, 16 | ] 17 | 18 | gobject_test_lib = shared_library( 19 | 'gobjecttester', 20 | sources: gobject_test_c, 21 | dependencies: gobject_test_deps, 22 | install: false, 23 | ) 24 | 25 | gobject_test_dep = declare_dependency( 26 | link_with: gobject_test_lib, 27 | include_directories: include_directories('.'), 28 | dependencies: gobject_test_deps, 29 | sources: gobject_test_public_h, 30 | ) -------------------------------------------------------------------------------- /tests/gtkdocentities.ent.in: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | -------------------------------------------------------------------------------- /tests/gtkdoctest.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | suite=$1 4 | dir=`dirname $0` 5 | 6 | cd $dir/$suite/docs && \ 7 | env BUILDDIR=$BUILDDIR/$suite/docs SRCDIR=$SRCDIR/$suite/docs gtkdoc-check 8 | -------------------------------------------------------------------------------- /tests/helpers/gtkdoc_check_runner.py: -------------------------------------------------------------------------------- 1 | # -*- python -*- 2 | 3 | from __future__ import print_function 4 | 5 | import argparse 6 | import os 7 | import sys 8 | 9 | from subprocess import call 10 | 11 | if __name__ == '__main__': 12 | parser = argparse.ArgumentParser(description='gtkdoc-check runner.') 13 | 14 | parser.add_argument("--binary-dir", type=str, required=True, 15 | help='Path to be used as a working directory') 16 | parser.add_argument("--input-dir", type=str, required=True, 17 | help='Path to be used as a working directory') 18 | parser.add_argument("--output-dir", type=str, required=True, 19 | help='Path to be used as a working directory') 20 | 21 | options, arguments = parser.parse_known_args() 22 | 23 | arguments.insert(0, os.path.join(options.binary_dir, 'gtkdoc-check')) 24 | 25 | environ = os.environ.copy() 26 | 27 | environ['SRCDIR'] = options.input_dir 28 | environ['BUILDDIR'] = options.output_dir 29 | 30 | sys.exit(call(arguments, env=environ)) -------------------------------------------------------------------------------- /tests/helpers/gtkdoc_fixxref_runner.py: -------------------------------------------------------------------------------- 1 | # -*- python -*- 2 | 3 | from __future__ import print_function 4 | 5 | import argparse 6 | import os 7 | import sys 8 | 9 | from subprocess import call 10 | 11 | if __name__ == '__main__': 12 | parser = argparse.ArgumentParser(description='gtkdoc-fixxref runner.') 13 | 14 | parser.add_argument("--binary-dir", type=str, required=True, 15 | help='Path to be used as a working directory') 16 | parser.add_argument("--change-dir", type=str, default=None, 17 | help='Path to be used as a working directory') 18 | 19 | options, arguments = parser.parse_known_args() 20 | 21 | arguments.insert(0, os.path.join(options.binary_dir, 'gtkdoc-fixxref')) 22 | 23 | if options.change_dir is not None: 24 | if not os.path.exists(options.change_dir): 25 | os.makedirs(options.change_dir) 26 | 27 | sys.exit(call(arguments, cwd=options.change_dir)) -------------------------------------------------------------------------------- /tests/helpers/gtkdoc_mkdb_runner.py: -------------------------------------------------------------------------------- 1 | # -*- python -*- 2 | 3 | from __future__ import print_function 4 | 5 | import argparse 6 | import os 7 | import sys 8 | 9 | from subprocess import call 10 | 11 | if __name__ == '__main__': 12 | parser = argparse.ArgumentParser(description='gtkdoc-mkdb runner.') 13 | 14 | parser.add_argument("--binary-dir", type=str, required=True, 15 | help='Path to be used as a working directory') 16 | parser.add_argument("--change-dir", type=str, default=None, 17 | help='Path to be used as a working directory') 18 | 19 | options, arguments = parser.parse_known_args() 20 | 21 | arguments.insert(0, os.path.join(options.binary_dir, 'gtkdoc-mkdb')) 22 | 23 | if options.change_dir is not None: 24 | if not os.path.exists(options.change_dir): 25 | os.makedirs(options.change_dir) 26 | 27 | sys.exit(call(arguments, cwd=options.change_dir)) -------------------------------------------------------------------------------- /tests/helpers/gtkdoc_mkhtml_runner.py: -------------------------------------------------------------------------------- 1 | # -*- python -*- 2 | 3 | from __future__ import print_function 4 | 5 | import argparse 6 | import os 7 | import shutil 8 | import sys 9 | 10 | from subprocess import call 11 | 12 | if __name__ == '__main__': 13 | parser = argparse.ArgumentParser(description='gtkdoc-mkhtml runner.') 14 | 15 | parser.add_argument("--binary-dir", type=str, required=True, 16 | help='Path to be used as a working directory') 17 | parser.add_argument("--change-dir", type=str, default=None, 18 | help='Path to be used as a working directory') 19 | parser.add_argument("--html-assets", type=str, default=None, 20 | help='List of HTML assets, seprated by "@@"') 21 | 22 | options, arguments = parser.parse_known_args() 23 | 24 | arguments.insert(0, os.path.join(options.binary_dir, 'gtkdoc-mkhtml')) 25 | 26 | if options.change_dir is not None: 27 | if not os.path.exists(options.change_dir): 28 | os.makedirs(options.change_dir) 29 | 30 | if not options.html_assets is None: 31 | for html_asset in options.html_assets.split('@@'): 32 | if options.change_dir is not None: 33 | html_target = os.path.join(options.change_dir, os.path.basename(html_asset)) 34 | else: 35 | html_target = os.path.join(os.getcwd(), os.path.basename(html_asset)) 36 | shutil.copyfile(html_asset, html_target) 37 | 38 | sys.exit(call(arguments, cwd=options.change_dir)) -------------------------------------------------------------------------------- /tests/helpers/gtkdoc_scan_runner.py: -------------------------------------------------------------------------------- 1 | # -*- python -*- 2 | 3 | from __future__ import print_function 4 | 5 | import argparse 6 | import os 7 | import sys 8 | 9 | from subprocess import call 10 | 11 | if __name__ == '__main__': 12 | parser = argparse.ArgumentParser(description='gtkdoc-scan runner.') 13 | 14 | parser.add_argument("--binary-dir", type=str, required=True, 15 | help='Path to be used as a working directory') 16 | parser.add_argument("--change-dir", type=str, default=None, 17 | help='Path to be used as a working directory') 18 | 19 | options, arguments = parser.parse_known_args() 20 | 21 | arguments.insert(0, os.path.join(options.binary_dir, 'gtkdoc-scan')) 22 | 23 | if options.change_dir is not None: 24 | if not os.path.exists(options.change_dir): 25 | os.makedirs(options.change_dir) 26 | 27 | sys.exit(call(arguments, cwd=options.change_dir)) -------------------------------------------------------------------------------- /tests/helpers/gtkdoc_scangobj_runner.py: -------------------------------------------------------------------------------- 1 | # -*- python -*- 2 | 3 | from __future__ import print_function 4 | 5 | import argparse 6 | import os 7 | import sys 8 | 9 | from subprocess import call, PIPE, Popen 10 | 11 | if __name__ == '__main__': 12 | parser = argparse.ArgumentParser(description='gtkdoc-scangobj runner.') 13 | 14 | parser.add_argument("--binary-dir", type=str, required=True, 15 | help='Path to be used as a working directory') 16 | parser.add_argument("--pkg-config", type=str, required=True, 17 | help='Path to the pkg-config executable to be used') 18 | parser.add_argument("--extra-pkg", type=str, default=[], action='append', 19 | help='Extra package to be use while scanning') 20 | parser.add_argument("--extra-cflags", type=str, default=[], action='append', 21 | help='Extra Cflags to be use while scanning') 22 | parser.add_argument("--extra-lib", type=str, default=[], action='append', 23 | help='Extra library to be use while scanning') 24 | 25 | options, arguments = parser.parse_known_args() 26 | 27 | arguments.insert(0, os.path.join(options.binary_dir, 'gtkdoc-scangobj')) 28 | 29 | process = Popen([options.pkg_config, 30 | '--cflags'] + options.extra_pkg, 31 | stdout=PIPE, stderr=PIPE) 32 | 33 | output, error = process.communicate() 34 | if process.returncode == 0: 35 | cflags = output.rstrip().decode('utf-8') 36 | arguments.append('--cflags={0}'.format(cflags)) 37 | 38 | for flag in options.extra_cflags: 39 | arguments.append('--cflags={0}'.format(flag)) 40 | 41 | process = Popen([options.pkg_config, 42 | '--libs'] + options.extra_pkg, 43 | stdout=PIPE, stderr=PIPE) 44 | 45 | output, error = process.communicate() 46 | if process.returncode == 0: 47 | arguments.append('--ldflags={0}'.format(output.rstrip().decode('utf-8'))) 48 | 49 | for lib in options.extra_lib: 50 | arguments.append('--ldflags=-l{0}'.format(os.path.basename(lib).split('.')[0].lstrip('lib'))) 51 | arguments.append('--ldflags=-L{0}'.format(os.path.dirname(lib))) 52 | arguments.append('--ldflags=-Wl,-rpath,{0}'.format(os.path.dirname(lib))) 53 | 54 | sys.exit(call(arguments)) 55 | -------------------------------------------------------------------------------- /tests/helpers/meson.build: -------------------------------------------------------------------------------- 1 | gtkdoc_scan_runner_script = files('gtkdoc_scan_runner.py') 2 | gtkdoc_scangobj_runner_script = files('gtkdoc_scangobj_runner.py') 3 | gtkdoc_mkdb_runner_script = files('gtkdoc_mkdb_runner.py') 4 | gtkdoc_mkhtml_runner_script = files('gtkdoc_mkhtml_runner.py') 5 | gtkdoc_fixxref_runner_script = files('gtkdoc_fixxref_runner.py') 6 | gtkdoc_check_runner_script = files('gtkdoc_check_runner.py') -------------------------------------------------------------------------------- /tests/highlight.py: -------------------------------------------------------------------------------- 1 | # -*- python -*- 2 | # 3 | # gtk-doc - GTK DocBook documentation generator. 4 | # Copyright (C) 2018 Stefan Sauer 5 | # 6 | # This program is free software; you can redistribute it and/or modify 7 | # it under the terms of the GNU General Public License as published by 8 | # the Free Software Foundation; either version 2 of the License, or 9 | # (at your option) any later version. 10 | # 11 | # This program is distributed in the hope that it will be useful, 12 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 13 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 | # GNU General Public License for more details. 15 | # 16 | # You should have received a copy of the GNU General Public License 17 | # along with this program; if not, write to the Free Software 18 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 19 | # 20 | 21 | import unittest 22 | 23 | from gtkdoc import highlight 24 | 25 | 26 | class HighlightTestCase(unittest.TestCase): 27 | 28 | def test_AlwaysKnowsCLang(self): 29 | code = highlight.highlight_code('void main(int argc, char **argv') 30 | self.assertIsNotNone(code) 31 | 32 | 33 | if __name__ == '__main__': 34 | unittest.main() 35 | -------------------------------------------------------------------------------- /tests/meson.build: -------------------------------------------------------------------------------- 1 | gtkdoc_unit_tests = [ 2 | 'check', 3 | 'common', 4 | 'highlight', 5 | 'mkdb', 6 | 'mk-to-db', 7 | 'mkhtml2', 8 | 'scan', 9 | ] 10 | 11 | test_env = environment() 12 | test_env.append('PYTHONPATH', srcdir, builddir) 13 | 14 | foreach test_name: gtkdoc_unit_tests 15 | test( 16 | 'test-unit-@0@'.format(test_name), 17 | python_prg, 18 | env: test_env, 19 | args: [ 20 | join_paths( 21 | srcdir, 22 | 'tests', 23 | '@0@.py'.format(test_name.underscorify()), 24 | ) 25 | ], 26 | ) 27 | endforeach 28 | 29 | subdir('helpers') 30 | 31 | glib_dep = dependency('glib-2.0', version: glib_req) 32 | gobject_dep = dependency('gobject-2.0', version: glib_req) 33 | 34 | glib_prefix = glib_dep.get_variable(pkgconfig: 'prefix') 35 | glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html') 36 | 37 | gobject_prefix = gobject_dep.get_variable(pkgconfig: 'prefix') 38 | gobject_docpath = join_paths(gobject_prefix, 'share', 'gtk-doc', 'html') 39 | 40 | subdir('annotations') 41 | subdir('bugs') 42 | subdir('empty') 43 | subdir('fail') 44 | subdir('gobject') 45 | subdir('program') 46 | -------------------------------------------------------------------------------- /tests/program.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -e 4 | 5 | gtkdoctest.sh program 6 | sanity.sh program 7 | -------------------------------------------------------------------------------- /tests/program/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | SUBDIRS = . src docs 4 | 5 | if BUILD_TESTS 6 | 7 | check-local: clean 8 | 9 | endif 10 | 11 | EXTRA_DIST = meson.build 12 | 13 | -include $(top_srcdir)/git.mk 14 | -------------------------------------------------------------------------------- /tests/program/docs/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | # We require automake 1.6 at least. 4 | AUTOMAKE_OPTIONS = 1.6 5 | 6 | # The name of the module, e.g. 'glib'. 7 | DOC_MODULE=tester 8 | 9 | # The top-level SGML file. You can change this if you want to. 10 | DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml 11 | 12 | # The directory containing the source code. Relative to $(srcdir). 13 | # gtk-doc will search all .c & .h files beneath here for inline comments 14 | # documenting the functions and macros. 15 | DOC_SOURCE_DIR=$(top_srcdir)/tests/program/src 16 | 17 | # Extra options to pass to gtkdoc-scangobj. Not normally needed. 18 | SCANGOBJ_OPTIONS= 19 | 20 | # Extra options to supply to gtkdoc-scan. 21 | SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ 22 | --rebuild-types 23 | 24 | # Extra options to supply to gtkdoc-mkdb. 25 | MKDB_OPTIONS=--xml-mode 26 | 27 | # Extra options to supply to gtkdoc-mkhtml 28 | MKHTML_OPTIONS= 29 | 30 | # Extra options to supply to gtkdoc-fixref. Not normally needed. 31 | # --html-dir=$(HTML_DIR) 32 | FIXXREF_OPTIONS=--extra-dir=$(glib_prefix)/share/gtk-doc/html 33 | 34 | # Used for dependencies. The docs will be rebuilt if any of these change. 35 | HFILE_GLOB= 36 | CFILE_GLOB=$(top_srcdir)/tests/program/src/*.c 37 | 38 | # Header files to ignore when scanning. 39 | IGNORE_HFILES=config.h 40 | 41 | # Images to copy into HTML directory. 42 | HTML_IMAGES = 43 | 44 | # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). 45 | # e.g. content_files=running.sgml building.sgml changes-2.0.sgml 46 | content_files = 47 | 48 | # SGML files where gtk-doc abbreviations (#GtkWidget) are expanded 49 | # These files must be listed here *and* in content_files 50 | # e.g. expand_content_files=running.sgml 51 | expand_content_files= 52 | 53 | # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. 54 | # Only needed if you are using gtkdoc-scangobj to dynamically query widget 55 | # signals and properties. 56 | GTKDOC_CFLAGS = 57 | GTKDOC_LIBS = 58 | 59 | # include generic part 60 | include $(top_srcdir)/tests/gtk-doc.make 61 | 62 | # Other files to distribute 63 | # e.g. EXTRA_DIST += version.xml.in 64 | EXTRA_DIST += 65 | 66 | CLEANFILES += \ 67 | $(DOC_MODULE)-overrides.txt \ 68 | $(DOC_MODULE).types 69 | 70 | if BUILD_TESTS 71 | TESTS_ENVIRONMENT = \ 72 | DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ 73 | PATH=$(abs_top_builddir):$(srcdir):$(PATH) 74 | endif 75 | 76 | EXTRA_DIST += meson.build 77 | EXTRA_DIST += xml/meson.build 78 | 79 | -include $(top_srcdir)/git.mk 80 | -------------------------------------------------------------------------------- /tests/program/docs/meson.build: -------------------------------------------------------------------------------- 1 | program_test_source_dir = join_paths( 2 | srcdir, 3 | 'tests', 4 | 'program', 5 | 'src' 6 | ) 7 | 8 | program_test_docs_dir = join_paths( 9 | srcdir, 10 | 'tests', 11 | 'program', 12 | 'docs' 13 | ) 14 | 15 | program_test_output_dir = join_paths( 16 | builddir, 17 | 'tests', 18 | 'program', 19 | 'docs' 20 | ) 21 | 22 | program_test_html_data = [] 23 | 24 | subdir('xml') 25 | 26 | test( 27 | 'test-program-scan', 28 | python_prg, 29 | workdir: program_test_docs_dir, 30 | is_parallel: false, 31 | args: [ 32 | gtkdoc_scan_runner_script, 33 | '--binary-dir=@0@'.format(builddir), 34 | '--change-dir=@0@'.format(program_test_output_dir), 35 | '--module=@0@'.format('tester'), 36 | '--source-dir=@0@'.format(program_test_source_dir), 37 | '--ignore-headers=config.h', 38 | '--deprecated-guards=GTKDOC_TESTER_DISABLE_DEPRECATED', 39 | '--rebuild-types', 40 | ], 41 | ) 42 | 43 | test( 44 | 'test-program-mkdb', 45 | python_prg, 46 | workdir: program_test_output_dir, 47 | is_parallel: false, 48 | args: [ 49 | gtkdoc_mkdb_runner_script, 50 | '--binary-dir=@0@'.format(builddir), 51 | '--module=@0@'.format('tester'), 52 | '--source-dir=@0@'.format(program_test_source_dir), 53 | '--main-sgml-file=@0@'.format('tester-docs.xml'), 54 | '--output-format=xml', 55 | '--xml-mode', 56 | ], 57 | ) 58 | 59 | foreach style_data: gtkdoc_style_data 60 | program_test_html_data += join_paths(srcdir, 'style', style_data) 61 | endforeach 62 | 63 | test( 64 | 'test-program-mkhtml', 65 | python_prg, 66 | workdir: program_test_output_dir, 67 | is_parallel: false, 68 | args: [ 69 | gtkdoc_mkhtml_runner_script, 70 | '--binary-dir=@0@'.format(builddir), 71 | '--change-dir=@0@'.format(join_paths(program_test_output_dir, 'html')), 72 | '--html-assets=@0@'.format('@@'.join(program_test_html_data)), 73 | '@0@'.format('tester'), 74 | '@0@'.format(join_paths('..', 'tester-docs.xml')), 75 | '--uninstalled', 76 | '--path=@0@'.format(':'.join([ 77 | program_test_docs_dir, 78 | srcdir]) 79 | ), 80 | ], 81 | ) 82 | 83 | test( 84 | 'test-program-fixxref', 85 | python_prg, 86 | workdir: program_test_output_dir, 87 | is_parallel: false, 88 | args: [ 89 | gtkdoc_fixxref_runner_script, 90 | '--binary-dir=@0@'.format(builddir), 91 | '--module=@0@'.format('tester'), 92 | '--module-dir=@0@'.format('html'), 93 | '--extra-dir=@0@'.format(glib_docpath), 94 | ], 95 | ) 96 | 97 | test( 98 | 'test-program-check', 99 | python_prg, 100 | workdir: program_test_docs_dir, 101 | is_parallel: false, 102 | args: [ 103 | gtkdoc_check_runner_script, 104 | '--binary-dir=@0@'.format(builddir), 105 | '--input-dir=@0@'.format(program_test_docs_dir), 106 | '--output-dir=@0@'.format(program_test_output_dir), 107 | ], 108 | ) -------------------------------------------------------------------------------- /tests/program/docs/tester-docs.xml: -------------------------------------------------------------------------------- 1 | 2 | 6 | 7 | %gtkdocentities; 8 | ]> 9 | 10 | 11 | &package_name; Reference Manual 12 | 13 | for &package_string;. 14 | The latest version of this documentation can be found on-line at 15 | http://[SERVER]/&package_name;/. 16 | 17 | 18 | 19 | 20 | Programs 21 | 22 | 23 | 24 | 25 | API Index 26 | 27 | 28 | 29 | Index of deprecated API 30 | 31 | 32 | 33 | -------------------------------------------------------------------------------- /tests/program/docs/tester-sections.txt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GNOME/gtk-doc/6fafd62a12a86b774c3a48c00ee2c7bda1459ce4/tests/program/docs/tester-sections.txt -------------------------------------------------------------------------------- /tests/program/docs/xml/meson.build: -------------------------------------------------------------------------------- 1 | configure_file( 2 | input: join_paths(srcdir, 'tests', 'gtkdocentities.ent.in'), 3 | output: 'gtkdocentities.ent', 4 | configuration: binary_in, 5 | ) 6 | -------------------------------------------------------------------------------- /tests/program/meson.build: -------------------------------------------------------------------------------- 1 | subdir('docs') -------------------------------------------------------------------------------- /tests/program/src/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | if BUILD_TESTS 4 | 5 | noinst_PROGRAMS = test-program 6 | 7 | endif 8 | 9 | 10 | -include $(top_srcdir)/git.mk 11 | -------------------------------------------------------------------------------- /tests/program/src/test-program.c: -------------------------------------------------------------------------------- 1 | 2 | /** 3 | * PROGRAM:test-program 4 | * @short_description: A test program 5 | * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE* 6 | * @see_also: test(1) 7 | * @--arg1 *arg*: set arg1 to *arg* 8 | * @-v, --version: Print the version number 9 | * @-h, --help: Print the help message 10 | * 11 | * Long description of program. 12 | * 13 | * Returns: Zero on success, non-zero on failure 14 | */ 15 | 16 | int main(int argc, char **argv) 17 | { 18 | return 0; 19 | } 20 | -------------------------------------------------------------------------------- /tests/repro/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | SUBDIRS = . src docs 4 | 5 | if BUILD_TESTS 6 | 7 | check-local: clean 8 | 9 | endif 10 | 11 | EXTRA_DIST = meson.build 12 | 13 | -include $(top_srcdir)/git.mk 14 | -------------------------------------------------------------------------------- /tests/repro/docs/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | # We require automake 1.6 at least. 4 | AUTOMAKE_OPTIONS = 1.6 5 | 6 | # The name of the module, e.g. 'glib'. 7 | DOC_MODULE=tester 8 | 9 | # The top-level SGML file. You can change this if you want to. 10 | DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml 11 | 12 | # The directory containing the source code. Relative to $(srcdir). 13 | # gtk-doc will search all .c & .h files beneath here for inline comments 14 | # documenting the functions and macros. 15 | DOC_SOURCE_DIR=$(top_srcdir)/tests/repro/src 16 | 17 | # Extra options to pass to gtkdoc-scangobj. Not normally needed. 18 | SCANGOBJ_OPTIONS= 19 | 20 | # Extra options to supply to gtkdoc-scan. 21 | SCAN_OPTIONS=--rebuild-sections --rebuild-types 22 | 23 | # Extra options to supply to gtkdoc-mkdb. 24 | MKDB_OPTIONS=--xml-mode 25 | 26 | # Extra options to supply to gtkdoc-mkhtml 27 | MKHTML_OPTIONS= 28 | 29 | # Extra options to supply to gtkdoc-fixref. Not normally needed. 30 | # --html-dir=$(HTML_DIR) 31 | FIXXREF_OPTIONS=--extra-dir=$(glib_prefix)/share/gtk-doc/html 32 | 33 | # Used for dependencies. The docs will be rebuilt if any of these change. 34 | HFILE_GLOB=$(top_srcdir)/tests/repro/src/*.h 35 | CFILE_GLOB=$(top_srcdir)/tests/repro/src/*.c 36 | 37 | # Header files to ignore when scanning. 38 | IGNORE_HFILES=config.h 39 | 40 | # Images to copy into HTML directory. 41 | HTML_IMAGES = 42 | 43 | # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). 44 | # e.g. content_files=running.sgml building.sgml changes-2.0.sgml 45 | content_files = 46 | 47 | # SGML files where gtk-doc abbreviations (#GtkWidget) are expanded 48 | # These files must be listed here *and* in content_files 49 | # e.g. expand_content_files=running.sgml 50 | expand_content_files= 51 | 52 | # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. 53 | # Only needed if you are using gtkdoc-scangobj to dynamically query widget 54 | # signals and properties. 55 | GTKDOC_CFLAGS = -I$(top_srcdir)/tests/repro/src $(TEST_DEPS_CFLAGS) 56 | GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/repro/src/libtester.la 57 | 58 | # include generic part 59 | include $(top_srcdir)/tests/gtk-doc.make 60 | 61 | # Other files to distribute 62 | # e.g. EXTRA_DIST += version.xml.in 63 | EXTRA_DIST += 64 | 65 | CLEANFILES += \ 66 | $(DOC_MODULE)-overrides.txt \ 67 | $(DOC_MODULE).types 68 | 69 | if BUILD_TESTS 70 | TESTS_ENVIRONMENT = \ 71 | DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ 72 | PATH=$(abs_top_builddir):$(srcdir):$(PATH) 73 | endif 74 | 75 | CLEANFILES += \ 76 | tester-sections.txt 77 | 78 | EXTRA_DIST += meson.build 79 | 80 | -include $(top_srcdir)/git.mk 81 | -------------------------------------------------------------------------------- /tests/repro/docs/meson.build: -------------------------------------------------------------------------------- 1 | repro_test_source_dir = join_paths( 2 | srcdir, 3 | 'tests', 4 | 'repro', 5 | 'src' 6 | ) 7 | 8 | repro_test_docs_dir = join_paths( 9 | srcdir, 10 | 'tests', 11 | 'repro', 12 | 'docs' 13 | ) 14 | 15 | repro_test_output_dir = join_paths( 16 | builddir, 17 | 'tests', 18 | 'repro', 19 | 'docs' 20 | ) 21 | 22 | repro_test_html_data = [] 23 | 24 | subdir('xml') 25 | 26 | test( 27 | 'test-repro-scan', 28 | python_prg, 29 | workdir: repro_test_docs_dir, 30 | is_parallel: false, 31 | args: [ 32 | gtkdoc_scan_runner_script, 33 | '--binary-dir=@0@'.format(builddir), 34 | '--change-dir=@0@'.format(repro_test_output_dir), 35 | '--module=@0@'.format('tester'), 36 | '--source-dir=@0@'.format(repro_test_source_dir), 37 | '--ignore-headers=config.h', 38 | '--rebuild-sections', 39 | '--rebuild-types', 40 | ], 41 | ) 42 | 43 | test( 44 | 'test-repro-mkdb', 45 | python_prg, 46 | workdir: repro_test_output_dir, 47 | is_parallel: false, 48 | args: [ 49 | gtkdoc_mkdb_runner_script, 50 | '--binary-dir=@0@'.format(builddir), 51 | '--module=@0@'.format('tester'), 52 | '--source-dir=@0@'.format(repro_test_source_dir), 53 | '--main-sgml-file=@0@'.format('tester-docs.xml'), 54 | '--output-format=xml', 55 | '--xml-mode', 56 | ], 57 | ) 58 | 59 | foreach style_data: gtkdoc_style_data 60 | repro_test_html_data += join_paths(srcdir, 'style', style_data) 61 | endforeach 62 | 63 | test( 64 | 'test-repro-mkhtml', 65 | python_prg, 66 | workdir: repro_test_output_dir, 67 | is_parallel: false, 68 | args: [ 69 | gtkdoc_mkhtml_runner_script, 70 | '--binary-dir=@0@'.format(builddir), 71 | '--change-dir=@0@'.format(join_paths(repro_test_output_dir, 'html')), 72 | '--html-assets=@0@'.format('@@'.join(repro_test_html_data)), 73 | '@0@'.format('tester'), 74 | '@0@'.format(join_paths('..', 'tester-docs.xml')), 75 | '--uninstalled', 76 | '--path=@0@'.format(':'.join([ 77 | repro_test_docs_dir, 78 | srcdir]) 79 | ), 80 | ], 81 | ) 82 | 83 | test( 84 | 'test-repro-fixxref', 85 | python_prg, 86 | workdir: repro_test_output_dir, 87 | is_parallel: false, 88 | args: [ 89 | gtkdoc_fixxref_runner_script, 90 | '--binary-dir=@0@'.format(builddir), 91 | '--module=@0@'.format('tester'), 92 | '--module-dir=@0@'.format('html'), 93 | '--extra-dir=@0@'.format(glib_docpath), 94 | ], 95 | ) 96 | 97 | test( 98 | 'test-repro-check', 99 | python_prg, 100 | workdir: repro_test_docs_dir, 101 | is_parallel: false, 102 | args: [ 103 | gtkdoc_check_runner_script, 104 | '--binary-dir=@0@'.format(builddir), 105 | '--input-dir=@0@'.format(repro_test_docs_dir), 106 | '--output-dir=@0@'.format(repro_test_output_dir), 107 | ], 108 | ) -------------------------------------------------------------------------------- /tests/repro/docs/tester-docs.xml: -------------------------------------------------------------------------------- 1 | 2 | 6 | 7 | %gtkdocentities; 8 | ]> 9 | 10 | 11 | &package_name; Reference Manual 12 | 13 | for &package_string;. 14 | The latest version of this documentation can be found on-line at 15 | http://[SERVER]/&package_name;/. 16 | 17 | 18 | 19 | 20 | Tests 21 | 22 | 23 | 24 | 25 | API Index 26 | 27 | 28 | 29 | -------------------------------------------------------------------------------- /tests/repro/meson.build: -------------------------------------------------------------------------------- 1 | subdir('docs') -------------------------------------------------------------------------------- /tests/repro/src/Makefile.am: -------------------------------------------------------------------------------- 1 | ## Process this file with automake to produce Makefile.in 2 | 3 | if BUILD_TESTS 4 | 5 | noinst_LTLIBRARIES = libtester.la 6 | 7 | libtester_la_SOURCES = tester.c tester.h 8 | #libtester_la_LIBADD = $(TEST_DEPS_LIBS) 9 | 10 | AM_CPPFLAGS = $(TEST_DEPS_CFLAGS) 11 | 12 | endif 13 | 14 | 15 | -include $(top_srcdir)/git.mk 16 | -------------------------------------------------------------------------------- /tests/repro/src/tester.c: -------------------------------------------------------------------------------- 1 | /** 2 | * SECTION:tester 3 | * @short_description: module for gtk-doc unit test 4 | * 5 | * This is a minimal doc module to serve easy to debug repro cases. 6 | */ 7 | 8 | #include "tester.h" 9 | -------------------------------------------------------------------------------- /tests/repro/src/tester.h: -------------------------------------------------------------------------------- 1 | #ifndef GTKDOC_TESTER_H 2 | #define GTKDOC_TESTER_H 3 | 4 | #include 5 | 6 | // FIXME: this should not be needed, if we have a title + long-desc 7 | /** 8 | * FOO: 9 | * 10 | * Placeholder to have non empty docs. 11 | */ 12 | #define FOO 1 13 | 14 | #endif // GTKDOC_TESTER_H 15 | -------------------------------------------------------------------------------- /tests/tools.sh.in: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | suite="tools" 4 | 5 | failed=0 6 | tested=0 7 | 8 | echo "Running suite(s): gtk-doc-$suite"; 9 | 10 | # we use 'which' here as we override the path in TEST_ENVIRONMENT 11 | 12 | 13 | # test shell scripts 14 | for file in gtkdocize; do 15 | sh -n `which $file` 16 | if test $? != 0 ; then failed=`expr $failed + 1`; fi 17 | tested=`expr $tested + 1` 18 | done 19 | 20 | 21 | # test xsl files 22 | for file in $ABS_TOP_SRCDIR/*.xsl; do 23 | xmllint --noout --noent $file 24 | if test $? != 0 ; then failed=`expr $failed + 1`; fi 25 | tested=`expr $tested + 1` 26 | done 27 | 28 | 29 | # test python scripts 30 | # TODO: also test the module files 31 | for file in gtkdoc-check gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml gtkdoc-mkhtml2 gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase gtkdoc-scangobj; do 32 | fullfile=`which $file` 33 | @PYTHON@ -m py_compile $fullfile 34 | if test $? != 0 ; then failed=`expr $failed + 1`; fi 35 | tested=`expr $tested + 1` 36 | done 37 | 38 | 39 | # summary 40 | successes=`expr $tested - $failed` 41 | 42 | rate=`expr 100 \* $successes / $tested`; 43 | echo "$rate %: Checks $tested, Failures: $failed" 44 | 45 | test $failed = 0 46 | exit $? 47 | -------------------------------------------------------------------------------- /tools/c10e-html.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/python3 2 | # canonicalize html dirs to ease comaring them 3 | # 4 | # run as: 5 | # ./tools/c10e-html html 6 | 7 | import argparse 8 | import glob 9 | import re 10 | import os 11 | import sys 12 | 13 | from bs4 import BeautifulSoup 14 | 15 | 16 | def prettify(filename, parser='lxml', fixup=False): 17 | with open(filename, 'r') as doc: 18 | soup = BeautifulSoup(doc.read(), parser) 19 | with open(filename, 'w') as doc: 20 | html = soup.prettify() 21 | if fixup: 22 | # strip things that mkhtml2 is not producing to reduce the diff 23 | html = html.replace('a class="link" href', 'a href') 24 | html = html.replace(' target="_top"', '') 25 | html = html.replace('summary="Navigation header" ', '') 26 | html = html.replace(""" 27 | 28 | """, '') 29 | html = re.sub("""
30 |
31 | Generated by GTK-Doc V[.0-9]* 32 |
33 | """, '', html) 34 | html = re.sub(r'\s*

\s*

', '', html) 35 | html = re.sub(r'\s*\s*', '', html) 36 | html = re.sub(r'\s*
\s*
', '', html) 37 | html = re.sub(r'\s*]*>', '', html) 39 | doc.write(html) 40 | 41 | 42 | def main(htmldir): 43 | for filename in glob.glob(os.path.join(htmldir, '*.devhelp2')): 44 | prettify(filename, parser='lxml-xml') 45 | for filename in glob.glob(os.path.join(htmldir, '*.html')): 46 | prettify(filename, fixup=True) 47 | 48 | 49 | if __name__ == '__main__': 50 | parser = argparse.ArgumentParser( 51 | description='c10e-html - canonicalize html files for diffing') 52 | parser.add_argument('args', nargs='*', help='HTML_DIR') 53 | 54 | options = parser.parse_args() 55 | if len(options.args) < 1: 56 | sys.exit('Too few arguments') 57 | 58 | main(options.args[0]) 59 | -------------------------------------------------------------------------------- /tools/docpercentages.pl: -------------------------------------------------------------------------------- 1 | #!/usr/bin/perl -w 2 | 3 | ############################################################################# 4 | # Function : CreateValidSGMLID 5 | # Description : Creates a valid SGML 'id' from the given string. 6 | # NOTE: SGML ids are case-insensitive, so we have a few special 7 | # cases to avoid clashes of ids. 8 | # Arguments : $id - the string to be converted into a valid SGML id. 9 | ############################################################################# 10 | 11 | sub CreateValidSGMLID { 12 | my ($id) = $_[0]; 13 | 14 | # Append -CAPS to all all-caps identifiers 15 | 16 | # Special case, '_' would end up as '' so we use 'gettext-macro' instead. 17 | if ($id eq "_") { return "gettext-macro"; } 18 | 19 | if ($id !~ /[a-z]/) { $id .= "-CAPS" }; 20 | 21 | $id =~ s/[_ ]/-/g; 22 | $id =~ s/[,\.]//g; 23 | $id =~ s/^-*//; 24 | $id =~ s/::/-/g; 25 | 26 | return $id; 27 | } 28 | 29 | $BASEDIR=shift @ARGV; 30 | 31 | print < 33 | ModuleDocumented 34 | EOT 35 | 36 | my $row = 0; 37 | while (@ARGV) { 38 | my $percentage; 39 | my $documented; 40 | my $undocumented; 41 | my @undocumented_symbols; 42 | 43 | my $module_name = shift @ARGV; 44 | my $file = shift @ARGV; 45 | my $indexfile = shift @ARGV; 46 | 47 | open DOCUMENTED, "<$file" or die "Cannot open $file: $!\n"; 48 | 49 | while () { 50 | if (/(\d+)% (function|symbol) docs coverage/) { 51 | $percentage = $1; 52 | } elsif (/(\d+) (function|symbol)s documented/) { 53 | $documented = $1; 54 | } elsif (/(\d+) not documented/) { 55 | $undocumented = $1; 56 | } elsif (/^\s*(\w+)\s*$/) { 57 | push @undocumented_symbols, $1; 58 | } 59 | } 60 | 61 | close DOCUMENTED; 62 | 63 | my $complete = defined $percentage && defined $documented && defined $undocumented; 64 | if (!$complete) { 65 | die "Cannot parse documentation status file $file\n"; 66 | } 67 | 68 | my $total = $documented + $undocumented; 69 | 70 | my $directory; 71 | ($directory = $indexfile) =~ s@/[^/]*$@@; 72 | 73 | $bgcolor = ($row % 2 == 0) ? "#f7ebd3" : "#fffcf4"; 74 | 75 | print < 77 | $module_name 78 | $documented 79 | /$total 80 | ($percentage%) 81 | EOT 82 | if ($undocumented != 0) { 83 | print <[missing] 85 | EOT 86 | } 87 | print < 89 | EOT 90 | 91 | # 92 | # Print an index of undocumented symbols for this module 93 | # 94 | 95 | @undocumented_symbols = sort { uc($a) cmp uc($b) } @undocumented_symbols; 96 | 97 | my $base = "$BASEDIR/$directory"; 98 | 99 | open INDEX_SGML, "<$base/index.sgml" or die "Cannot open $base/index.sgml: $!\n"; 100 | 101 | my %index_symbols; 102 | 103 | while () { 104 | if (//) { 105 | $index_symbols{$1} = $2; 106 | } 107 | } 108 | 109 | close INDEX_SGML; 110 | 111 | open UNDOC_OUT, ">$base/undocumented.html" or die "Cannot open $base/undocumented.html: $!\n"; 112 | print UNDOC_OUT < 114 | 115 | Undocumented functions in $module_name 116 | 117 | 118 | 119 | 120 | EOT 121 | my $i = 0; 122 | for $symbol (@undocumented_symbols) { 123 | my $id = CreateValidSGMLID($symbol); 124 | 125 | my $output; 126 | if (exists $index_symbols{$id}) { 127 | my $href; 128 | 129 | ($href = $index_symbols{$id}) =~ s@.*/(.*)$@$1@; 130 | 131 | $output = qq($symbol); 132 | } else { 133 | $output = qq($symbol); 134 | } 135 | print UNDOC_OUT " \n"; 136 | if ($i % 3 == 2) { 137 | print UNDOC_OUT " \n"; 138 | } 139 | 140 | $i++; 141 | } 142 | 143 | print UNDOC_OUT < 145 |
$output
146 | 147 | 148 | EOT 149 | close UNDOC_OUT; 150 | $row++; 151 | } 152 | 153 | print < 155 | EOT 156 | -------------------------------------------------------------------------------- /tools/git-pre-commit: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | # git hook to ensure code style 3 | # cp tools/git-pre-commit .git/hooks/pre-commit 4 | # 5 | # TODO: 6 | # pylint -r n -f parseable $files 7 | 8 | which >/dev/null pep8 || (echo "please install pep8"; exit ) 9 | which >/dev/null autopep8 || (echo "please install autopep8"; exit ) 10 | which >/dev/null pyflakes || (echo "please install pyflakes"; exit ) 11 | 12 | files=$(git diff --name-only --staged --diff-filter=ACMRTUXB | egrep "*.py$") 13 | 14 | if test -n "$files"; then 15 | pep8 --max-line-length=120 $files 16 | res=$? 17 | if [ $res -ne 0 ]; then 18 | echo 19 | autopep8 --max-line-length=120 --diff $files 20 | echo 21 | echo "To fix run: autopep8 --max-line-length=120 -i $files" 22 | else 23 | pyflakes $files 24 | res=$? 25 | fi 26 | exit $res 27 | fi 28 | -------------------------------------------------------------------------------- /version-greater-or-equal.xsl: -------------------------------------------------------------------------------- 1 | 2 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 1 32 | 33 | 34 | 0 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 0 46 | 47 | 48 | 1 49 | 50 | 51 | 52 | 53 | 54 | 55 | --------------------------------------------------------------------------------