GNOME.org
 

[libadwaita/wip/exalm/gi-docgen: 1/40] Move docs to gi-docgen


commit bfe0c61568459f0c147c99c33acbfdf3a46559b5
Author: Alexander Mikhaylenko <alexm gnome org>
Date:   Fri May 7 14:04:23 2021 +0500

    Move docs to gi-docgen

 .gitlab-ci.yml                 |  12 +-
 .gitlab-ci/docs.Dockerfile     |  23 +++
 doc/adwaita-docs.xml           | 145 -----------------
 doc/build-howto.md             | 105 ++++++++++++
 doc/build-howto.xml            | 159 ------------------
 doc/hdy-migrating-0-0-to-1.xml | 356 -----------------------------------------
 doc/images/search.png          | Bin 17371 -> 0 bytes
 doc/libadwaita.svg             | 112 +++++++++++++
 doc/libadwaita.toml.in         |  52 ++++++
 doc/meson.build                |  98 +++++-------
 doc/urlmap.js                  |  10 ++
 doc/visual-index.md            |  11 ++
 doc/visual-index.xml           |  53 ------
 doc/xml/gtkdocentities.ent.in  |   9 --
 doc/xml/meson.build            |  12 --
 15 files changed, 355 insertions(+), 802 deletions(-)
---
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 47edcae6..adc9ce10 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -7,6 +7,7 @@ variables:
   FLATPAK_MODULE: 'libadwaita'
   FLATPAK_BUILD_DIR: build
   ABI_CHECKER_IMAGE: "registry.gitlab.gnome.org/gnome/libadwaita/abi-checker:v1"
+  DOCS_IMAGE: "registry.gitlab.gnome.org/gnome/libadwaita/docs:v1"
 
 stages:
   - build
@@ -19,7 +20,7 @@ api-visibility:
     - ./.gitlab-ci/api-visibility.sh
 
 doc:
-  image: registry.gitlab.gnome.org/gnome/gnome-runtime-images/gnome:master
+  image: $DOCS_IMAGE
   stage: build
   tags:
     - flatpak
@@ -27,12 +28,11 @@ doc:
     MESON_ARGS: >-
       -Dbuild-tests=false
       -Dgtk_doc=true
-      -Dintrospection=disabled
+      -Dvapi=false
   script:
-    - flatpak-builder --user --disable-rofiles-fuse --stop-at=${FLATPAK_MODULE} ${FLATPAK_BUILD_DIR} 
${MANIFEST_PATH}
-    - flatpak build ${FLATPAK_BUILD_DIR} meson --prefix=/app ${SHARED_MESON_ARGS} ${MESON_ARGS} _build
-    - flatpak build ${FLATPAK_BUILD_DIR} ninja -C _build libadwaita-1-doc
-    - mv _build/doc/html/ _doc/
+    - meson --prefix=/app ${MESON_ARGS} _build
+    - ninja -C _build
+    - mv _build/doc/libadwaita-1 _doc/
   artifacts:
     paths:
       - _doc
diff --git a/.gitlab-ci/docs.Dockerfile b/.gitlab-ci/docs.Dockerfile
new file mode 100644
index 00000000..b46ddb1a
--- /dev/null
+++ b/.gitlab-ci/docs.Dockerfile
@@ -0,0 +1,23 @@
+FROM fedora:34
+
+RUN dnf -y update \
+ && dnf -y install \
+    @development-tools \
+    dnf-plugins-core \
+    gcc \
+    git \
+    gobject-introspection-devel \
+    gtk4-devel \
+    meson \
+    pcre-static \
+    python3 \
+    python3-jinja2 \
+    python3-markdown \
+    python3-pip \
+    python3-pygments \
+    python3-toml \
+    python3-typogrify \
+    python3-wheel \
+    redhat-rpm-config \
+    sassc \
+ && dnf clean all
diff --git a/doc/build-howto.md b/doc/build-howto.md
new file mode 100644
index 00000000..be7db76f
--- /dev/null
+++ b/doc/build-howto.md
@@ -0,0 +1,105 @@
+Title: Compiling with Libadwaita
+Slug: building
+
+# Building
+
+If you need to build Libadwaita, get the source from
+[here](https://gitlab.gnome.org/GNOME/libadwaita/) and see the `README.md` file.
+
+# Using `pkg-config`
+
+Like other GNOME libraries, Libadwaita uses `pkg-config` to provide compiler
+options. The package name is `libadwaita-1`.
+
+If you use Automake/Autoconf, in your `configure.ac` script, you might specify
+something like:
+
+```autoconf
+PKG_CHECK_MODULES(LIBADWAITA, [libadwaita-1])
+AC_SUBST(LIBADWAITA_CFLAGS)
+AC_SUBST(LIBADWAITA_LIBS)
+```
+
+Or when using the Meson build system you can declare a dependency like:
+
+```meson
+dependency('libadwaita-1')
+```
+
+The `1` in the package name is the "API version" (indicating "the version of the
+Libadwaita API that first appeared in version 1") and is essentially just part
+of the package name.
+
+# Bundling the library
+
+As Libadwaita uses the Meson build system, bundling it as a subproject when it
+is not installed is easy. Add this to your `meson.build`:
+
+```meson
+libadwaita_dep = dependency('libadwaita-1', version: '>= 1.0.0', required: false)
+if not libadwaita_dep.found()
+libadwaita = subproject(
+  'libadwaita',
+  install: false,
+  default_options: [
+    'examples=false',
+    'package_subdir=my-project-name',
+    'tests=false',
+  ]
+)
+libadwaita_dep = libadwaita.get_variable('libadwaita_dep')
+endif
+```
+
+Then add Libadwaita as a git submodule:
+
+```bash
+git submodule add https://gitlab.gnome.org/GNOME/libadwaita.git subprojects/libadwaita
+```
+
+To bundle the library with your Flatpak application, add the following module to
+your manifest:
+
+```json
+{
+  "name" : "libadwaita",
+  "buildsystem" : "meson",
+  "builddir" : true,
+  "config-opts": [
+    "-Dexamples=false",
+    "-Dtests=false"
+  ],
+  "sources" : [
+    {
+      "type" : "git",
+      "url" : "https://gitlab.gnome.org/GNOME/libadwaita.git";
+    }
+  ]
+}
+```
+
+# Building on macOS
+
+To build on macOS you need to install the build-dependencies first. This can
+e.g. be done via [`brew`](https://brew.sh):
+
+```bash
+brew install pkg-config gtk+3 adwaita-icon-theme meson glade gobject-introspection vala
+```
+
+After running the command above, one may now build the library:
+
+```bash
+git clone https://gitlab.gnome.org/GNOME/libadwaita.git
+cd libadwaita
+meson . _build
+ninja -C _build test
+ninja -C _build install
+```
+
+Working with the library on macOS is pretty much the same as on Linux. To link
+it, use `pkg-config`:
+
+```bash
+gcc $(pkg-config --cflags --libs gtk+-3.0) $(pkg-config --cflags --libs libadwaita-1) main.c -o main
+```
diff --git a/doc/libadwaita.svg b/doc/libadwaita.svg
new file mode 100644
index 00000000..8601c042
--- /dev/null
+++ b/doc/libadwaita.svg
@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   width="48"
+   height="48"
+   viewBox="0 0 12.7 12.7"
+   version="1.1"
+   id="svg1077"
+   inkscape:version="1.1-beta1 (77e7b44db3, 2021-03-28)"
+   sodipodi:docname="libadwaita.svg"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape";
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd";
+   xmlns:xlink="http://www.w3.org/1999/xlink";
+   xmlns="http://www.w3.org/2000/svg";
+   xmlns:svg="http://www.w3.org/2000/svg";>
+  <sodipodi:namedview
+     id="namedview1079"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     objecttolerance="10.0"
+     gridtolerance="10.0"
+     guidetolerance="10.0"
+     inkscape:pageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:document-units="px"
+     showgrid="false"
+     inkscape:zoom="5.0457912"
+     inkscape:cx="42.510677"
+     inkscape:cy="7.9273989"
+     inkscape:window-width="1920"
+     inkscape:window-height="1011"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="layer1"
+     units="px" />
+  <defs
+     id="defs1074">
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient15144"
+       id="linearGradient15146"
+       x1="78.052086"
+       y1="86.518761"
+       x2="92.074997"
+       y2="86.254173"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="translate(-185.98349,-5.7118018)" />
+    <linearGradient
+       inkscape:collect="always"
+       id="linearGradient15144">
+      <stop
+         style="stop-color:#8ff0a4;stop-opacity:1"
+         offset="0"
+         id="stop15140" />
+      <stop
+         style="stop-color:#3584e4;stop-opacity:1"
+         offset="1"
+         id="stop15142" />
+    </linearGradient>
+  </defs>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-74.192375,-93.908467)">
+    <rect
+       
style="fill:url(#linearGradient15146);fill-opacity:1;stroke:none;stroke-width:0.264583;stroke-dashoffset:26.4"
+       id="rect4789"
+       width="12.7"
+       height="12.7"
+       x="-106.60847"
+       y="74.192375"
+       transform="rotate(-90)"
+       inkscape:export-xdpi="384"
+       inkscape:export-ydpi="384"
+       ry="6.3499999"
+       rx="6.3499999" />
+    <g
+       id="g14982"
+       transform="translate(-5.182627,14.004305)">
+      <rect
+         
style="opacity:0.5;fill:#000000;fill-opacity:0;stroke:none;stroke-width:0.264583;stroke-dashoffset:26.4"
+         id="rect4791"
+         width="8.4666672"
+         height="8.4666672"
+         x="81.491669"
+         y="82.020836" />
+      <g
+         id="g1405-3"
+         transform="matrix(0.79375001,0,0,0.79375001,-33.262333,-105.35835)"
+         style="display:inline;fill:#ffffff;stroke-width:2;enable-background:new">
+        <path
+           
style="display:inline;opacity:0.95;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.916672px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;enable-background:new"
+           d="m 144.57197,241.06826 h 5.66667 v 5.66667 z"
+           id="path1358-3-6"
+           sodipodi:nodetypes="cccc" />
+        <path
+           
style="display:inline;opacity:0.75;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.611114px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;enable-background:new"
+           d="m 154.23864,237.06826 h -4 v 4 z"
+           id="path1360-6-7"
+           sodipodi:nodetypes="cccc" />
+        <path
+           
style="display:inline;opacity:0.4;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.458336px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;enable-background:new"
+           d="m 150.23864,241.06826 h 3 v 3 z"
+           id="path1362-7-5"
+           sodipodi:nodetypes="cccc" />
+      </g>
+    </g>
+  </g>
+</svg>
diff --git a/doc/libadwaita.toml.in b/doc/libadwaita.toml.in
new file mode 100644
index 00000000..11e78475
--- /dev/null
+++ b/doc/libadwaita.toml.in
@@ -0,0 +1,52 @@
+[library]
+version = "@VERSION@"
+description = "Building blocks for modern GNOME applications"
+authors = "Purism SPC"
+license = "GPL-2.1-or-later"
+browse_url = "https://gitlab.gnome.org/GNOME/libadwaita/";
+repository_url = "https://gitlab.gnome.org/GNOME/libadwaita.git";
+website_url = "https://gnome.pages.gitlab.gnome.org/libadwaita";
+logo_url = "libadwaita.svg"
+dependencies = [
+  "GObject-2.0",
+  "Gtk-4.0",
+]
+devhelp = true
+search_index = true
+
+[dependencies."GObject-2.0"]
+name = "GObject"
+description = "The base type system library"
+docs_url = "https://developer.gnome.org/gobject/stable";
+
+[dependencies."Gtk-4.0"]
+name = "GTK"
+description = "The GTK toolkit"
+docs_url = "https://docs.gtk.org/gtk4/";
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+# The base URL for the web UI
+base_url = "https://gitlab.gnome.org/GNOME/libadwaita/-/blob/main/";
+# The format for links, using "filename" and "line" for the format
+file_format = "{filename}#L{line}"
+
+[extra]
+urlmap_file = "urlmap.js"
+content_files = [
+  "build-howto.md",
+  "visual-index.md",
+]
+content_images = [
+  "images/avatar.png",
+  "images/header-bar.png",
+  "images/list.png",
+  "images/preferences-window.png",
+  "images/view-switcher.png",
+  "images/view-switcher-bar.png",
+  "libadwaita.svg",
+]
diff --git a/doc/meson.build b/doc/meson.build
index bf8ab5fb..6e765a65 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -1,71 +1,45 @@
 if get_option('gtk_doc')
 
-subdir('xml')
-
-private_headers = [
-    'config.h',
-    'gtkprogresstrackerprivate.h',
-    'gtk-window-private.h',
-    'adw-animation-private.h',
-    'adw-enums.h',
-    'adw-enums-private.h',
-    'adw-enum-value-object-private.h',
-    'adw-focus-private.h',
-    'adw-gizmo-private.h',
-    'adw-indicator-bin-private.h',
-    'adw-main-private.h',
-    'adw-preferences-group-private.h',
-    'adw-preferences-page-private.h',
-    'adw-shadow-helper-private.h',
-    'adw-swipe-tracker-private.h',
-    'adw-view-switcher-button-private.h',
-    'adw-window-mixin-private.h',
+expand_content_md_files = [
+  'build-howto.md',
+  'visual-index.md',
 ]
 
-images = [
-  'images/avatar.png',
-  'images/header-bar.png',
-  'images/list.png',
-  'images/preferences-window.png',
-  'images/search.png',
-  'images/view-switcher.png',
-  'images/view-switcher-bar.png',
-]
+toml_data = configuration_data()
+toml_data.set('VERSION', meson.project_version())
 
-content_files = [
-  'build-howto.xml',
-  'hdy-migrating-0-0-to-1.xml',
-  'visual-index.xml',
-]
+libadwaita_toml = configure_file(
+  input: 'libadwaita.toml.in',
+  output: 'libadwaita.toml',
+  configuration: toml_data
+)
+
+dependency('gi-docgen', version: '>= 2021.1',
+           fallback: ['gi-docgen', 'dummy_dep'],
+           required: get_option('gtk_doc'))
+
+gidocgen = find_program('gi-docgen')
 
-glib_prefix  = dependency('glib-2.0').get_pkgconfig_variable('prefix')
-glib_docpath = glib_prefix / 'share' / 'gtk-doc' / 'html'
-docpath      = get_option('datadir') / 'gtk-doc' / 'html'
+docs_dir = datadir / 'doc'
 
-gnome.gtkdoc('libadwaita',
-     module_version: apiversion,
-           main_xml: 'adwaita-docs.xml',
-            src_dir: [
-                       meson.source_root() / 'src',
-                       meson.build_root()  / 'src',
-                     ],
-       dependencies: libadwaita_dep,
-  gobject_typesfile: 'libadwaita.types',
-          scan_args: [
-                       '--rebuild-types',
-                       '--ignore-headers=' + ' '.join(private_headers),
-                     ],
-       fixxref_args: [
-                       '--html-dir=@0@'.format(docpath),
-                       '--extra-dir=@0@'.format(glib_docpath / 'glib'),
-                       '--extra-dir=@0@'.format(glib_docpath / 'gobject'),
-                       '--extra-dir=@0@'.format(glib_docpath / 'gio'),
-                       '--extra-dir=@0@'.format(glib_docpath / 'gi'),
-                       '--extra-dir=@0@'.format(glib_docpath / 'gtk3'),
-                       '--extra-dir=@0@'.format(glib_docpath / 'gdk-pixbuf'),
-                     ],
-      content_files: content_files,
-        html_assets: images,
-            install: true)
+custom_target('libadwaita-doc',
+  input: [ libadwaita_toml, libadwaita_gir[0] ],
+  output: 'libadwaita-@0@'.format(apiversion),
+  command: [
+    gidocgen,
+    'generate',
+    '--quiet',
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../src'),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--no-namespace-dir',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
+  ],
+  depend_files: [ expand_content_md_files ],
+  build_by_default: true,
+  install: true,
+  install_dir: docs_dir,
+)
 
 endif
diff --git a/doc/urlmap.js b/doc/urlmap.js
new file mode 100644
index 00000000..5b6039ef
--- /dev/null
+++ b/doc/urlmap.js
@@ -0,0 +1,10 @@
+// SPDX-FileCopyrightText: 2021 Purism SPC
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+  [ 'Gdk', 'https://docs.gtk.org/gdk4/' ],
+  [ 'Gsk', 'https://docs.gtk.org/gsk4/' ],
+  [ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
+  [ 'Pango', 'https://docs.gtk.org/Pango/' ],
+
diff --git a/doc/visual-index.md b/doc/visual-index.md
new file mode 100644
index 00000000..9c3df8d0
--- /dev/null
+++ b/doc/visual-index.md
@@ -0,0 +1,11 @@
+Title: Visual index
+Slug: visual-index
+
+# Widgets
+
+[![avatar](avatar.png)](class.Avatar.html)
+[![header-bar](header-bar.png)](class.HeaderBar.html)
+[![list](list.png)](class.ActionRow.html)
+[![preferences-window](preferences-window.png)](class.PreferencesWindow.html)
+[![view-switcher](view-switcher.png)](class.ViewSwitcher.html)
+[![view-switcher-bar](view-switcher-bar.png)](class.ViewSwitcherBar.html)
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]