From 233084070fec59465fbead5c525b11c385be74ed Mon Sep 17 00:00:00 2001 From: Christoph Reiter Date: Wed, 12 Dec 2018 09:32:44 +0100 Subject: docs: Remove everything not related to libgirepository and restructure. Fixes #244 The gtk-doc docs were including some bits of overal g-i docs but mostly unfinished and outdated. We now have the general docs in sphinx so remove the duplication and make the gtk-docs just about the libgirepository API and nothing more. This also renames some titles and fixes some missing links in the struct hierarchy while at it. --- docs/reference/Makefile.am | 8 - docs/reference/gi-docs.xml | 76 ++--- docs/reference/gi-gir-reference.xml | 123 -------- docs/reference/gi-sections.txt | 3 +- docs/reference/gi-struct-hierarchy.xml | 6 +- docs/reference/images/overview.png | Bin 112776 -> 0 bytes docs/reference/images/overview.svg | 494 -------------------------------- docs/reference/meson.build | 4 - docs/reference/overview-building.xml | 189 ------------ docs/reference/overview-programming.xml | 22 -- 10 files changed, 25 insertions(+), 900 deletions(-) delete mode 100644 docs/reference/gi-gir-reference.xml delete mode 100644 docs/reference/images/overview.png delete mode 100644 docs/reference/images/overview.svg delete mode 100644 docs/reference/overview-building.xml delete mode 100644 docs/reference/overview-programming.xml (limited to 'docs') diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index ed55e594..ee953bb7 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -57,17 +57,9 @@ IGNORE_HFILES= \ girmodule.h \ girepository-private.h -# Images to copy into HTML directory. -# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png -HTML_IMAGES= \ - images/overview.png - # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). # e.g. content_files=running.sgml building.sgml changes-2.0.sgml content_files= \ - overview-building.xml \ - overview-programming.xml \ - gi-gir-reference.xml \ gi-struct-hierarchy.xml \ version.xml diff --git a/docs/reference/gi-docs.xml b/docs/reference/gi-docs.xml index 352fe7ec..78db99ae 100644 --- a/docs/reference/gi-docs.xml +++ b/docs/reference/gi-docs.xml @@ -5,63 +5,30 @@ ]> - GObject Introspection Reference Manual + libgirepository API Reference - GObject Introspection Reference Manual + libgirepository API Reference - This document is for GObject Introspection version &version;. + This document is for libgirepository version &version;. The latest version of this documentation can be found on-line at - http://developer.gnome.org/gi/unstable/. + https://developer.gnome.org/gi/unstable/. + + For more information on how to build libgirepository, for how to build + bindings with it and for information on GObject Introspection in + general see + https://gi.readthedocs.io. + - - GObject-Introspection Overview - - GObject-Introspection is striving to provide a middleware layer between - (GObject based) C libraries and language bindings. The primary goal of - this project is to minimize duplicated effort in language binding - projects by providing shared metadata files on bound C libraries. - Language bindings can read these metadata files at runtime to learn - how to interface with a bound C library. - + + + - - - - - The GObject-Introspection package contains of a few different parts: - - - The GIR XML format - an XML format describing the exported C API including documentation - - - The GTypelib format - a binary format optimized for fast disk access and low memory usage - - - g-ir-scanner - parses C source code and gtk-doc comments and generates GIR XML files - - - g-ir-compiler - compiles GIR XML files into typelibs - - - libgirepository - library to access typelib from C - - - - The following illustration shows how the different components fit together: - - - - - API Reference - GIRepository - + GIBaseInfo - - @@ -85,20 +52,15 @@ - - GITypelib - - - - - TODO + FFI Interface - - - + + Internals & Typelib Format + + Index diff --git a/docs/reference/gi-gir-reference.xml b/docs/reference/gi-gir-reference.xml deleted file mode 100644 index 04c85662..00000000 --- a/docs/reference/gi-gir-reference.xml +++ /dev/null @@ -1,123 +0,0 @@ - - - -]> - - - The GIR XML format - 3 - The GIR XML format - - - The GIR XML format - The GIR XML format - - - - This chapter describes the GIR XML markup format. This describes exported C - API, including documentation. It may contain installation-specific data, - such as library filenames which may differ between platforms. - - - - <emphasis>api</emphasis> node - - The root node of all GIR documents is the api node. - - Possible children: namespace. - - - A GIR fragment showing an api node - - - ]]> - - - - - <emphasis>namespace</emphasis> node - - Parent node: api. - Possible children: callback, - class, - function. - interface. - - - A GIR fragment showing an namespace node - - - - - - ]]> - - - - - <emphasis>class</emphasis> node - - Parent node: namespace. - Possible children: constructor, - field, - method, - property. - - A GIR fragment showing an class node - - - - - - - - - - ]]> - - - - - <emphasis>interface</emphasis> node - - Parent node: namespace. - Possible children: field, - method, - property. - - A GIR fragment showing an interface node - - - - - - - - - ]]> - - - - - <emphasis>function</emphasis> node - - Parent node: namespace. - - A GIR fragment showing an function node - - - - - - ]]> - - - - diff --git a/docs/reference/gi-sections.txt b/docs/reference/gi-sections.txt index 3fe4bea8..40841438 100644 --- a/docs/reference/gi-sections.txt +++ b/docs/reference/gi-sections.txt @@ -94,6 +94,8 @@ g_base_info_is_deprecated GI_TYPE_BASE_INFO g_base_info_gtype_get_type + +GIUnresolvedInfo
@@ -140,7 +142,6 @@ g_callable_info_skip_return
gicommontypes GIArgument -GIUnresolvedInfo GITypeTag GIArrayType GI_TYPE_TAG_N_TYPES diff --git a/docs/reference/gi-struct-hierarchy.xml b/docs/reference/gi-struct-hierarchy.xml index fc77c2f8..685f85aa 100644 --- a/docs/reference/gi-struct-hierarchy.xml +++ b/docs/reference/gi-struct-hierarchy.xml @@ -22,19 +22,21 @@ * GIBaseInfo * GICallableInfo * GIFunctionInfo + * GICallbackInfo * GISignalInfo * GIVFuncInfo * GIRegisteredTypeInfo * GIEnumInfo - * GIInterfaceInfo - * GIObjectInfo * GIStructInfo * GIUnionInfo + * GIObjectInfo + * GIInterfaceInfo * GIArgInfo * GIConstantInfo * GIFieldInfo * GIPropertyInfo * GITypeInfo + * GIValueInfo diff --git a/docs/reference/images/overview.png b/docs/reference/images/overview.png deleted file mode 100644 index b4a12bda..00000000 Binary files a/docs/reference/images/overview.png and /dev/null differ diff --git a/docs/reference/images/overview.svg b/docs/reference/images/overview.svg deleted file mode 100644 index 6a004f6d..00000000 --- a/docs/reference/images/overview.svg +++ /dev/null @@ -1,494 +0,0 @@ - - - - - - - - - - - image/svg+xml - - - - - - - - - Introspected GType's - - - Sources .c - - - - Headers .h - - - - - GIR - XML format withintrospectable metadataa language binding needfunction,class,enum,docstrings, struct fieldsetc - g-ir-scanner(1) - g-ir-compiler(1) - - - - - - Typelib - binaryformat for fastdisk-access andlow memory - - Build time - Runtime - - - How a language binding uses introspection - How a library enables introspection - - Typelib - mmap()shared betweenprocesses - - - libgirepository - - - - libffi - - - - - dlopen:ed library - - - - diff --git a/docs/reference/meson.build b/docs/reference/meson.build index b6173116..3d2a5567 100644 --- a/docs/reference/meson.build +++ b/docs/reference/meson.build @@ -22,11 +22,7 @@ gnome.gtkdoc('gi', main_xml: 'gi-docs.xml', dependencies: girepo_dep, src_dir: 'girepository', - html_assets: 'images/overview.png', content_files: [ - 'overview-building.xml', - 'overview-programming.xml', - 'gi-gir-reference.xml', 'gi-struct-hierarchy.xml', ], scan_args: [ diff --git a/docs/reference/overview-building.xml b/docs/reference/overview-building.xml deleted file mode 100644 index 7c843ce3..00000000 --- a/docs/reference/overview-building.xml +++ /dev/null @@ -1,189 +0,0 @@ - - - - - Compiling the GObject Introspection package - - - - Compiling the GObject Introspection Package - How to compile GObject Introspection itself - - - - Building on UNIX - - On UNIX, GObject Introspection uses the standard GNU build system, - using autoconf for package - configuration and resolving portability issues, - automake for building makefiles - that comply with the GNU Coding Standards, and - libtool for building shared - libraries on multiple platforms. The normal sequence for - compiling and installing the GObject Introspection package is thus: - - - ./configure - make - make install - - - - - The standard options provided by GNU - autoconf may be passed to the - configure script. Please see the - autoconf documentation or run - ./configure --help for information about - the standard options. - - - - - Dependencies - - Before you can compile GObject Introspection, you need to have - various other tools and libraries installed on your - system. The tools needed during the build process (as - differentiated from the basic build tools mentioned - before are: - - - - - pkg-config - is a tool for tracking the compilation flags needed for - libraries that are used by the GObjecct Introspection. (For each - library, a small .pc text file is - installed in a standard location that contains the compilation - flags needed for that library along with version number - information.) - - - - - The GObject-Introspection makefiles will mostly work with different - versions of make, however, there tends to be a - few incompatibilities, so the GObject-Introspection team recommends - installing GNU - make if you don't already have it on your system - and using it. (It may be called gmake - rather than make.) - - - - - GObject-Introspection depends on a number of libraries and tools - maintained under the umbrella of the GNOME project: - - - - - The GLib library provides core non-graphical functionality - such as high level data types, Unicode manipulation, and - an object and type system to C programs. It is available - from the GNOME - FTP site or - here. - - - - - TODO: GTK-Doc - - - - - External dependencies - - - Python - - - - - GObject Introspection has an option dependency on the - libffi library. When available, - ... - - - - - - Cairo - is a graphics library that supports vector graphics and image - compositing. When available, GObject Introspection uses - Cairo in its unit tests. - - - - - - - - Extra Configuration Options - - - In addition to the normal options, the - configure script in the GObject Introspection - package supports these additional arguments: - - - - <systemitem>--disable-Bsymbolic</systemitem> and - <systemitem>--enable-Bsymbolic</systemitem> - - - By default, the GObject Introspection package uses the - -Bsymbolic-functions linker flag to avoid intra-library - PLT jumps. A side-effect of this is that it is no longer - possible to override internal uses of GObject Introspection - functions with LD_PRELOAD. Therefore, it may - make sense to turn this feature off in some situations. - The option allows - to do that. - - - - - <systemitem>--disable-gtk-doc</systemitem> and - <systemitem>--enable-gtk-doc</systemitem> - - - By default the configure script will try - to auto-detect whether the - gtk-doc package is installed. - If it is, then it will use it to extract and build the - documentation for the GObject Introspection package. These options - can be used to explicitly control whether - gtk-doc should be - used or not. If it is not used, the distributed, - pre-generated HTML files will be installed instead of - building them on your machine. - - - - - <systemitem>--disable-doctool</systemitem> and - <systemitem>--enable-doctool</systemitem> - - - TODO - - - - - <systemitem>--with-python</systemitem> - - - Allows specifying the Python interpreter to use, either as an - absolute path, or as a program name. GObject Introspection can - be built with Python 2 (at least version 2.6) but does not yet - support Python 3. - - - - - diff --git a/docs/reference/overview-programming.xml b/docs/reference/overview-programming.xml deleted file mode 100644 index 6511d4b7..00000000 --- a/docs/reference/overview-programming.xml +++ /dev/null @@ -1,22 +0,0 @@ - - - - - Writing introspected libraries - - - - Writing introspected libraries - General considerations when writing introspected libraries - - - - TODO - - ... - - - - -- cgit v1.2.1