GNOME.org
 

[gobject-introspection: 1/2] docs: Remove everything not related to libgirepository and restructure. Fixes #244

commit 233084070fec59465fbead5c525b11c385be74ed
Author: Christoph Reiter <reiter christoph gmail com>
Date:   Wed Dec 12 09:32:44 2018 +0100

    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.

 .gitlab-ci.yml                          |   2 +-
 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 --
 girepository/docs.c                     |   2 +-
 girepository/gitypelib-internal.h       |   2 +-
 girepository/gitypelib.h                |   2 +-
 14 files changed, 29 insertions(+), 904 deletions(-)
---
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index f478377a..92ddbf59 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -21,7 +21,7 @@ fedora-x86_64-meson:
     - ninja gi-doc
     - cd ..
     - mkdir -p public
-    - mv _build/docs/reference/html/ public/docs/
+    - mv _build/docs/reference/html/ public/girepository/
     - python3 -m pip install --user flake8
     - python3 -m flake8 --count
   except:
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 @@
 <!ENTITY version SYSTEM "xml/version.xml">
 ]>
 <book id="index" lang="en" xmlns:xi="http://www.w3.org/2003/XInclude";>
-  <title>GObject Introspection Reference Manual</title>
+  <title>libgirepository API Reference</title>
   <bookinfo>
-    <title>GObject Introspection Reference Manual</title>
+    <title>libgirepository API Reference</title>
     <releaseinfo>
-      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
-      <ulink type="http" 
url="http://developer.gnome.org/gi/unstable/";>http://developer.gnome.org/gi/unstable/</ulink>.
+      <ulink type="http" 
url="https://developer.gnome.org/gi/unstable/";>https://developer.gnome.org/gi/unstable/</ulink>.
+      <para>
+        For more information on how to build libgirepository, for how to build
+        bindings with it and for information on GObject Introspection in
+        general see
+        <ulink type="http" url="https://gi.readthedocs.io";>https://gi.readthedocs.io</ulink>.
+      </para>
     </releaseinfo>
   </bookinfo>
 
-  <part id="overview">
-    <title>GObject-Introspection Overview</title>
-    <para>
-      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.
-    </para>
+    <xi:include href="xml/girepository.xml"/>
+    <xi:include href="xml/gitypelib.xml" />
+    <xi:include href="xml/gicommontypes.xml"/>
 
-    <xi:include href="xml/overview-building.xml"/>
-    <xi:include href="xml/overview-programming.xml"/>
-
-    <para>
-      The GObject-Introspection package contains of a few different parts:
-      <itemizedlist>
-        <listitem>
-          <para>The GIR XML format - an XML format describing the exported C API including 
documentation</para>
-        </listitem>
-        <listitem>
-          <para>The GTypelib format - a binary format optimized for fast disk access and low memory 
usage</para>
-        </listitem>
-        <listitem>
-          <para>g-ir-scanner - parses C source code and gtk-doc comments and generates GIR XML files</para>
-        </listitem>
-        <listitem>
-          <para>g-ir-compiler - compiles GIR XML files into typelibs</para>
-        </listitem>
-        <listitem>
-          <para>libgirepository - library to access typelib from C</para>
-        </listitem>
-      </itemizedlist>
-    </para>
-    <para>The following illustration shows how the different components fit together:</para>
-    <inlinegraphic fileref="overview.png" format="PNG"></inlinegraphic>
-  </part>
-
-  <part id="gi">
-    <title>API Reference</title>
     <chapter>
-      <title>GIRepository</title>
-      <xi:include href="xml/girepository.xml"/>
+      <title>GIBaseInfo</title>
       <xi:include href="xml/gi-struct-hierarchy.xml"/>
 
-      <xi:include href="xml/gicommontypes.xml"/>
-
       <xi:include href="xml/gibaseinfo.xml"/>
 
       <xi:include href="xml/gicallableinfo.xml"/>
@@ -85,20 +52,15 @@
       <xi:include href="xml/givalueinfo.xml"/>
     </chapter>
 
-    <chapter id="gi-typelib">
-      <title>GITypelib</title>
-      <xi:include href="xml/gitypelib.xml" />
-      <xi:include href="xml/gitypelib-internal.xml"/>
-    </chapter>
-
     <chapter>
-      <title>TODO</title>
+      <title>FFI Interface</title>
       <xi:include href="xml/girffi.xml"/>
-
-      <xi:include href="xml/gi-gir-reference.xml"/>
     </chapter>
 
-  </part>
+    <chapter>
+      <title>Internals &amp; Typelib Format</title>
+      <xi:include href="xml/gitypelib-internal.xml"/>
+    </chapter>
 
   <index id="api-index-full">
     <title id="index-all">Index</title>
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
 <SUBSECTION Standard>
 GI_TYPE_BASE_INFO
 g_base_info_gtype_get_type
+<SUBSECTION Private>
+GIUnresolvedInfo
 </SECTION>
 
 <SECTION>
@@ -140,7 +142,6 @@ g_callable_info_skip_return
 <SECTION>
 <FILE>gicommontypes</FILE>
 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 @@
 * <link linkend="GIBaseInfo">GIBaseInfo</link>
   * <link linkend="gi-GICallableInfo">GICallableInfo</link>
     * <link linkend="gi-GIFunctionInfo">GIFunctionInfo</link>
+    * <link linkend="gi-GICallbackInfo">GICallbackInfo</link>
     * <link linkend="gi-GISignalInfo">GISignalInfo</link>
     * <link linkend="gi-GIVFuncInfo">GIVFuncInfo</link>
   * <link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
     * <link linkend="gi-GIEnumInfo">GIEnumInfo</link>
-    * <link linkend="gi-GIInterfaceInfo">GIInterfaceInfo</link>
-    * <link linkend="gi-GIObjectInfo">GIObjectInfo</link>
     * <link linkend="gi-GIStructInfo">GIStructInfo</link>
     * <link linkend="gi-GIUnionInfo">GIUnionInfo</link>
+    * <link linkend="gi-GIObjectInfo">GIObjectInfo</link>
+    * <link linkend="gi-GIInterfaceInfo">GIInterfaceInfo</link>
   * <link linkend="gi-GIArgInfo">GIArgInfo</link>
   * <link linkend="gi-GIConstantInfo">GIConstantInfo</link>
   * <link linkend="gi-GIFieldInfo">GIFieldInfo</link>
   * <link linkend="gi-GIPropertyInfo">GIPropertyInfo</link>
   * <link linkend="gi-GITypeInfo">GITypeInfo</link>
+  * <link linkend="gi-GIValueInfo">GIValueInfo</link>
 </synopsis>
 
 </refsynopsisdiv>
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/girepository/docs.c b/girepository/docs.c
index a4798c41..b032b823 100644
--- a/girepository/docs.c
+++ b/girepository/docs.c
@@ -26,7 +26,7 @@
 
 /**
  * SECTION:gicommontypes
- * @title: common types
+ * @title: Common Types
  * @short_description: TODO
  *
  * TODO
diff --git a/girepository/gitypelib-internal.h b/girepository/gitypelib-internal.h
index b44ba041..28b177d6 100644
--- a/girepository/gitypelib-internal.h
+++ b/girepository/gitypelib-internal.h
@@ -31,7 +31,7 @@ G_BEGIN_DECLS
 
 /**
  * SECTION:gitypelib-internal
- * @title: GITypelib
+ * @title: GITypelib Internals
  * @short_description: Layout and accessors for typelib
  * @stability: Stable
  *
diff --git a/girepository/gitypelib.h b/girepository/gitypelib.h
index 7d0a6654..e6f46bcf 100644
--- a/girepository/gitypelib.h
+++ b/girepository/gitypelib.h
@@ -35,7 +35,7 @@ G_BEGIN_DECLS
 
 /**
  * SECTION:gitypelib
- * @title: gitypelib
+ * @title: GITypelib
  * @short_description: TODO
  *
  * TODO
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]