brl/gnome-shell
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: Switch documentation to gi-docgen

Browse Source 
Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/1873>
This commit is contained in:
Zander Brown 2021-06-07 01:04:55 +01:00 committed by Florian Müllner
parent ebe1a4d303
commit 4373a91911
14 changed files with 166 additions and 207 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
docs/reference/meson.build
View File

@ -1,5 +1,18 @@
version_conf = configuration_data()
version_conf.set('VERSION', meson.project_version())
gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
doc_conf = configuration_data()
doc_conf.set('MUTTER_API_VERSION', mutter_api_version)
gi_docgen_common_args = [
'--quiet',
'--no-namespace-dir',
]
if get_option('werror')
gi_docgen_common_args += ['--fatal-warnings']
endif
docs_dir = datadir / 'doc'
subdir('shell')
subdir('st')

68
docs/reference/shell/meson.build
View File

@ -1,51 +1,25 @@
private_headers = [
'gactionmuxer.h',
'gactionobservable.h',
'gactionobserver.h',
'shell-network-agent.h',
]
exclude_directories = [
'calendar-server',
'hotplug-sniffer',
'st',
'tray'
]
ifaces = [
['org.gnome.Shell.Screenshot', 'org.gnome.Shell.Screenshot.xml'],
['org.gnome.ShellSearchProvider', 'org.gnome.Shell.SearchProvider.xml'],
['org.gnome.ShellSearchProvider2', 'org.gnome.Shell.SearchProvider2.xml']
]
foreach iface : ifaces
custom_target(iface[0] + ' docs',
input: '../../../data/dbus-interfaces/@0@.xml'.format(iface[0]),
output: 'doc-gen-' + iface[1],
command: [
'gdbus-codegen',
'--interface-prefix=@0@.'.format(iface[0]),
'--generate-docbook', 'doc-gen',
'--output-directory', '@OUTDIR@',
'@INPUT@'
],
build_by_default: true
)
endforeach
configure_file(
input: 'version.xml.in',
output: 'version.xml',
configuration: version_conf
shell_toml = configure_file(
input: 'shell.toml.in',
output: 'shell.toml',
configuration: doc_conf
)
gnome.gtkdoc('shell',
main_sgml: 'shell-docs.sgml',
src_dir: [
join_paths(meson.project_source_root(), 'src'),
join_paths(meson.project_build_root(), 'src')
custom_target('shell-doc',
input: [shell_toml, libshell_gir[0]],
output: 'shell',
command: [
gidocgen,
'generate',
gi_docgen_common_args,
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../src'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../src/st'),
'--add-include-path=@0@'.format(mutter_dep.get_variable('girdir')),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../subprojects/gvc'),
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
scan_args: [
'--ignore-headers=' + ' '.join(private_headers + exclude_directories)
],
install: true
install: true,
install_dir: docs_dir,
)

67
docs/reference/shell/shell-docs.sgml
View File

@ -1,67 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index">
<bookinfo>
<title>Shell Reference Manual</title>
<releaseinfo>
for Shell &version;.
<!--The latest version of this documentation can be found on-line at
<ulink role="online-location" url="http://[SERVER]/shell/index.html">http://[SERVER]/shell/</ulink>.-->
</releaseinfo>
</bookinfo>
<chapter>
<title>Actors</title>
<xi:include href="xml/shell-stack.xml"/>
</chapter>
<chapter>
<title>Application tracking</title>
<xi:include href="xml/shell-app.xml"/>
<xi:include href="xml/shell-app-usage.xml"/>
<xi:include href="xml/shell-window-tracker.xml"/>
</chapter>
<chapter>
<title>Search</title>
<xi:include href="xml/shell-app-system.xml"/>
</chapter>
<chapter>
<title>Tray Icons</title>
<xi:include href="xml/shell-tray-icon.xml"/>
<xi:include href="xml/shell-tray-manager.xml"/>
</chapter>
<chapter>
<title>Integration helpers and utilities</title>
<xi:include href="doc-gen-org.gnome.Shell.SearchProvider.xml"/>
<xi:include href="doc-gen-org.gnome.Shell.SearchProvider2.xml"/>
<xi:include href="xml/shell-global.xml"/>
<xi:include href="xml/shell-action-modes.xml"/>
<xi:include href="xml/shell-wm.xml"/>
<xi:include href="xml/shell-util.xml"/>
<xi:include href="xml/shell-mount-operation.xml"/>
<xi:include href="xml/shell-polkit-authentication-agent.xml"/>
</chapter>
<!-- FIXME:
Not generated at the moment, find out whether to blame gtk-doc or meson
-->
<!--
<chapter id="object-tree">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
</chapter>
-->
<index id="api-index-full">
<title>API Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<index id="deprecated-api-index" role="deprecated">
<title>Index of deprecated API</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>

41
docs/reference/shell/shell.toml.in Normal file
View File

@ -0,0 +1,41 @@
[library]
namespace = "Shell"
version = "@MUTTER_API_VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/gnome-shell/"
repository_url = "https://gitlab.gnome.org/GNOME/gnome-shell.git"
website_url = "https://www.gnome.org"
license = "GPL-2.0-or-later"
description = "Shell"
dependencies = ["GObject-2.0", "Gio-2.0", "Meta-@MUTTER_API_VERSION@", "Clutter-@MUTTER_API_VERSION@"]
devhelp = true
search_index = true
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject"
[dependencies."Gio-2.0"]
name = "Gio"
description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
docs_url = "https://docs.gtk.org/gio"
[dependencies."Meta-@MUTTER_API_VERSION@"]
name = "Meta"
description = "The mutter display server, window manager and compositor library"
docs_url = "https://gnome.pages.gitlab.gnome.org/mutter/meta/"
[dependencies."Clutter-@MUTTER_API_VERSION@"]
name = "Clutter"
description = "An OpenGL based 'interactive canvas' library"
docs_url = "https://gnome.pages.gitlab.gnome.org/mutter/clutter/"
[theme]
name = "basic"
show_index_summary = true
[source-location]
base_url = "https://gitlab.gnome.org/GNOME/gnome-shell/-/blob/HEAD/"
[extra]
urlmap_file = "urlmap.js"

11
docs/reference/shell/urlmap.js Normal file
View File

@ -0,0 +1,11 @@
baseURLs = [
[ 'GLib', 'https://docs.gtk.org/glib/' ],
[ 'GObject', 'https://docs.gtk.org/gobject/' ],
[ 'Gio', 'https://docs.gtk.org/gio/' ],
[ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
[ 'Meta', 'https://gnome.pages.gitlab.gnome.org/mutter/meta/' ],
[ 'Mtk', 'https://gnome.pages.gitlab.gnome.org/mutter/mtk/' ],
[ 'Cogl', 'https://gnome.pages.gitlab.gnome.org/mutter/cogl/' ],
[ 'Clutter', 'https://gnome.pages.gitlab.gnome.org/mutter/clutter/' ],
[ 'St', 'https://gnome.pages/gitlab.gnome.org/gnome-shell/st/' ],
]

1
docs/reference/shell/version.xml.in
View File

@ -1 +0,0 @@
@VERSION@

39
docs/reference/st/meson.build
View File

@ -1,23 +1,24 @@
private_headers = [
'st-private.h',
'st-theme-node-private.h'
]
configure_file(
input: 'version.xml.in',
output: 'version.xml',
configuration: version_conf
st_toml = configure_file(
input: 'st.toml.in',
output: 'st.toml',
configuration: doc_conf
)
gnome.gtkdoc('st',
main_sgml: 'st-docs.sgml',
src_dir: [
join_paths(meson.project_source_root(), 'src', 'st'),
join_paths(meson.project_build_root(), 'src', 'st')
custom_target('st-doc',
input: [st_toml, libst_gir[0]],
output: 'st',
command: [
gidocgen,
'generate',
gi_docgen_common_args,
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../src'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../src/st'),
'--add-include-path=@0@'.format(mutter_dep.get_variable('girdir')),
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
scan_args: [
'--ignore-headers=' + ' '.join(private_headers),
'--rebuild-sections'
],
install: true
install: true,
install_dir: docs_dir,
)

69
docs/reference/st/st-docs.sgml
View File

@ -1,69 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index">
<bookinfo>
<title>St Reference Manual</title>
<releaseinfo>
for St &version;.
<!--The latest version of this documentation can be found on-line at
<ulink role="online-location" url="http://[SERVER]/st/index.html">http://[SERVER]/st/</ulink>.-->
</releaseinfo>
</bookinfo>
<part>
<title>API reference</title>
<chapter id="base">
<title>Abstract classes and Interfaces</title>
<xi:include href="xml/st-widget.xml"/>
<xi:include href="xml/st-widget-accessible.xml"/>
<xi:include href="xml/st-scrollable.xml"/>
</chapter>
<chapter id="widgets">
<title>Widgets</title>
<xi:include href="xml/st-button.xml"/>
<xi:include href="xml/st-drawing-area.xml"/>
<xi:include href="xml/st-entry.xml"/>
<xi:include href="xml/st-icon.xml"/>
<xi:include href="xml/st-label.xml"/>
</chapter>
<chapter id="containers">
<title>Containers</title>
<xi:include href="xml/st-bin.xml"/>
<xi:include href="xml/st-box-layout.xml"/>
<xi:include href="xml/st-scroll-view.xml"/>
</chapter>
<chapter id="styling">
<title>Styling</title>
<xi:include href="xml/st-theme.xml"/>
<xi:include href="xml/st-theme-context.xml"/>
<xi:include href="xml/st-theme-node.xml"/>
<xi:include href="xml/st-theme-node-transition.xml"/>
<xi:include href="xml/st-texture-cache.xml"/>
</chapter>
</part>
<!-- FIXME:
Not generated at the moment, find out whether to blame gtk-doc or meson
-->
<!--
<chapter id="object-tree">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
</chapter>
-->
<index id="api-index-full">
<title>API Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<index id="deprecated-api-index" role="deprecated">
<title>Index of deprecated API</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>

36
docs/reference/st/st.toml.in Normal file
View File

@ -0,0 +1,36 @@
[library]
namespace = "St"
version = "@MUTTER_API_VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/gnome-shell/"
repository_url = "https://gitlab.gnome.org/GNOME/gnome-shell.git"
website_url = "https://www.gnome.org"
license = "LGPL-2.0-or-later"
description = "Shell Toolkit"
dependencies = ["GObject-2.0", "Gio-2.0", "Clutter-@MUTTER_API_VERSION@"]
devhelp = true
search_index = true
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject"
[dependencies."Gio-2.0"]
name = "Gio"
description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
docs_url = "https://docs.gtk.org/gio"
[dependencies."Clutter-@MUTTER_API_VERSION@"]
name = "Clutter"
description = "An OpenGL based 'interactive canvas' library"
docs_url = "https://gnome.pages.gitlab.gnome.org/mutter/clutter/"
[theme]
name = "basic"
show_index_summary = true
[source-location]
base_url = "https://gitlab.gnome.org/GNOME/gnome-shell/-/blob/HEAD/"
[extra]
urlmap_file = "urlmap.js"

10
docs/reference/st/urlmap.js Normal file
View File

@ -0,0 +1,10 @@
baseURLs = [
[ 'GLib', 'https://docs.gtk.org/glib/' ],
[ 'GObject', 'https://docs.gtk.org/gobject/' ],
[ 'Gio', 'https://docs.gtk.org/gio/' ],
[ 'Pango', 'https://docs.gtk.org/pango/' ],
[ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
[ 'Clutter', 'https://gnome.pages.gitlab.gnome.org/mutter/clutter/' ],
[ 'Cogl', 'https://gnome.pages.gitlab.gnome.org/mutter/cogl/' ],
[ 'Meta', 'https://gnome.pages.gitlab.gnome.org/mutter/meta/' ],
]

1
docs/reference/st/version.xml.in
View File

@ -1 +0,0 @@
@VERSION@

5
meson.build
View File

@ -95,6 +95,11 @@ x11_dep = dependency('x11')
schemas_dep = dependency('gsettings-desktop-schemas', version: schemas_req)
gnome_desktop_dep = dependency('gnome-desktop-4', version: gnome_desktop_req)
gidocgen_dep = dependency('gi-docgen',
version: '>= 2021.1',
fallback: ['gi-docgen', 'dummy_dep'],
required: get_option('gtk_doc'))
nm_deps = []
if get_option('networkmanager')
nm_deps += dependency('libnm', version: nm_req)

2
src/meson.build
View File

@ -231,7 +231,7 @@ libshell_gir_includes += [
libst_gir[0]
]
gnome.generate_gir(libshell,
libshell_gir = gnome.generate_gir(libshell,
sources: libshell_gir_sources,
nsversion: mutter_api_version,
namespace: 'Shell',

6
subprojects/gi-docgen.wrap Normal file
View File

@ -0,0 +1,6 @@
[wrap-git]
directory=gi-docgen
url=https://gitlab.gnome.org/GNOME/gi-docgen.git
push-url=ssh://git@gitlab.gnome.org:GNOME/gi-docgen.git
revision=main
depth=1