Commit Graph

2985 Commits

Author SHA1 Message Date
Philip Withnall
4314944e56 introspection: Drop Unix and Win32 prefixes from platform specific APIs
So now introspection users will have to call `GLibUnix.open_pipe()`
rather than `GLibUnix.unix_open_pipe()` — or
`GLibWin32.check_windows_version()` rather than
`GLibWin32.win32_check_windows_version()`.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2024-02-12 17:54:36 +00:00
Philip Withnall
434d3ff524 docs: Mention GioUnix-2.0 GIR namespace alongside gio-unix-2.0.pc
This should clarify things a little for users of language bindings, who
don’t directly use `.pc` files.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-02-12 17:54:10 +00:00
Philip Withnall
c498c9a8c9 docs: Split out platform specific GIO and GLib documentation
This creates `GioUnix`, `GioWin32`, `GLibUnix` and `GLibWin32`. These
bodies of documentation are in addition to the main, platform agnostic,
documentation for both libraries.

This commit necessarily includes various mechanical changes to update
the repository namespace used in various existing documentation links to
platform specific APIs.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2024-02-12 17:54:10 +00:00
Philip Withnall
4c178fa623 build: Combine duplicate urlmap.js files
Seems no point in keeping them separate. It doesn’t seem to matter if
they contain entries which are unused for a particular docs build.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-02-12 17:54:10 +00:00
Philip Withnall
3695249ebb docs: Drop unnecessary GdkPixbuf reference from urlmap.js
It was unused.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-02-12 17:54:10 +00:00
Philip Withnall
f51398af91 girepository: Drop GIBoxedInfo
See the previous commit for details.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3245
2024-02-12 13:17:04 +00:00
Philip Withnall
8248382d8b gi-inspect-repository: Change --version argument to --typelib-version
`--version` is conventionally used to find the version of the program
itself. While that’s not currently implemented in
`gi-inspect-repository`, let’s not box ourselves into a corner.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-02-09 20:41:17 +00:00
Philip Withnall
d6d845aee3 docs: Add missing migration guide for gi_repository_get_shared_libraries()
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-02-09 20:40:47 +00:00
Philip Withnall
45468f1bb8 docs: Document girepository-2.0 utility program name changes
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-02-09 20:40:46 +00:00
Philip Withnall
343027d5de girepository: Make GIInfoType private
Eventually, we want to move to using `GType` directly for everything,
since `GIBaseInfo` and its subclasses are all using `GTypeInstance`.

However, that requires quite a lot of changes and we’re about to hit the
API freeze.

So do the smallest set of changes possible to remove `GIInfoType` and
related functions from the public API, which gives us freedom to make
more changes later without breaking API.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3155
2024-02-08 12:56:02 +00:00
Philip Withnall
86cd95f1ae Merge branch 'gi-info-new' into 'main'
gibaseinfo: Rename gi_info_new() to gi_base_info_new()

See merge request GNOME/glib!3903
2024-02-08 10:34:40 +00:00
Philip Withnall
beb59595b7 gibaseinfo: Rename gi_info_new() to gi_base_info_new()
It’s actually a factory method rather than a constructor, since
`GIBaseInfo` is abstract, but despite that, changing the name so it sits
inside the `GIBaseInfo` class makes sense. There is no `GIInfo` type.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3155
2024-02-08 10:34:40 +00:00
Philip Withnall
e1cff511e5 Merge branch '3155-union-tests' into 'main'
gitypes: Fix integer values of GIInfoType and add unit tests for GIUnionInfo

See merge request GNOME/glib!3888
2024-02-08 10:25:13 +00:00
Philip Withnall
78698af73f Merge branch '3246-object-info-docs' into 'main'
girepository: Fix declaration of ‘find using interfaces’ methods

Closes #3246

See merge request GNOME/glib!3883
2024-02-08 10:19:16 +00:00
Philip Withnall
62abd578cd Merge branch '3155-typelib-boxed' into 'main'
gitypelib: Switch to refcounting

See merge request GNOME/glib!3900
2024-02-08 10:18:40 +00:00
Philip Withnall
a138589d57 Merge branch 'repository-n-elements' into 'main'
girepository: Add length ‘out’ arguments to several getter methods

See merge request GNOME/glib!3901
2024-02-08 10:18:12 +00:00
Philip Withnall
6fe7edbc8d Merge branch 'girepository-migration-docs' into 'main'
docs: Add migration guide for libgirepository

See merge request GNOME/glib!3881
2024-02-08 10:10:40 +00:00
Philip Withnall
5cc5f413f5 gitypelib: Switch to refcounting
Since `GITypelib` is exposed in the public libgirepository API, it needs
to be a boxed type. So we either need to add a `copy` method to mirror
the existing `free` method, or switch to refcounting. The latter option
seems better, since a `GITypelib` contains internal state about open
`GModule`s and the semantics for copying that would be potentially
complex.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3155
2024-02-07 21:07:18 +00:00
Philip Withnall
01f9796532 girepository: Add length ‘out’ arguments to several getter methods
This makes them consistent with the other getter methods in
`GIRepository` which return lists/arrays. It’s useful to return the
length, as that means the caller doesn’t have to work it out by
iterating over the entire array.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3155
2024-02-07 15:47:13 +00:00
Simon McVittie
040caa5f6a gdbus-codegen(1): Suggest --pragma-once for headers written to stdout
Otherwise we would generate a multiple-inclusion guard of the
form `#ifndef __STDOUT__ ...`, which can only work for one D-Bus
interface per translation unit.

Signed-off-by: Simon McVittie <smcv@collabora.com>
2024-02-06 14:06:51 +00:00
Simon McVittie
fc7942f46b gdbus-codegen: If writing body to stdout, don't try to include header
If we're writing the body to standard output, we cannot know what the
filename of the corresponding header is going to be, but it seems
vanishingly unlikely that it will be either `stdout.h` (which we would
traditionally have generated) or `-.h` (which we would have generated
since !3886).

This makes some of the output snippets sufficiently short that black(1)
requires that they are folded into a single line.

Signed-off-by: Simon McVittie <smcv@collabora.com>
2024-02-06 14:06:45 +00:00
Philip Withnall
11e8075e51 giunioninfo: Split success and return value for get_discriminator_offset()
Otherwise there’s no obvious suitable return value to return when the
union is *not* discriminated.

This is an API break, but libgirepository has not been in a stable
release yet, so that’s fine.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3155
2024-02-06 13:34:17 +00:00
Simon McVittie
1ba8386886 codegen: Document --output -
Signed-off-by: Simon McVittie <smcv@collabora.com>
2024-02-06 11:53:06 +00:00
Philip Withnall
7acef299c2 girepository: Fix declaration of ‘find using interfaces’ methods
Fix the declaration and documentation of
`gi_object_info_find_method_using_interfaces()` and
`gi_object_info_find_vfunc_using_interfaces()`. The documentation was
wrong when I wrote it: the value returned is the object or interface
which declares the method or vfunc, not the one which implements it.

The returned declarer info may be a `GIObjectInfo` or a
`GIInterfaceInfo`. Since those two types have no subtype relation
between them, the return type has to be changed to `GIBaseInfo`. Using
`GIObjectInfo` would have been fine in girepository-1.0 because all
`*Info` types were aliases of each other — but since the move to
`GTypeInstance` this is no longer true.

A unit test will be in the following commit.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Fixes: #3246
2024-02-05 18:40:03 +00:00
Philip Withnall
702719dee9 build: Ensure the libgirepository docs are installed
Make the `meson.build` match the other docs `meson.build` files.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-02-05 18:03:52 +00:00
Philip Withnall
bad849347d docs: Add migration guide for libgirepository
This covers all the API changes from girepository-1.0 to
girepository-2.0 so far.

It was generated by manually looking through the changes in `git diff
af36393e6.. -- girepository/*.h`.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3155
2024-02-05 18:03:52 +00:00
Jordan Petridis
e0b7ab81cf docs: Fix include path for the build
f75221c7ea moved the introspection
folder around, but we also need to adjust the relative path so
the documentation will keep building
2024-02-02 12:54:07 +02:00
Michael Catanzaro
8f34e90bc3 Link to the main context tutorial from the main loop docs
This might help increase visibility of Philip's useful GMainContext
tutorial. Although the GMainContext documentation is fairly good, it's
also pretty intimidating. The tutorial is very useful and provides
guidance that we can't fit directly into the documentation, so reference
it.
2024-01-31 11:56:56 -06:00
Emmanuele Bassi
4ff4f073a4 Merge branch 'altiera/docs' into 'main'
docs: Fix links to symbols outside the allowed namsepace

See merge request GNOME/glib!3809
2024-01-18 18:35:21 +00:00
Emmanuele Bassi
b5c07063c3 docs: Use code for class names in links
So that they fit with the documentation guidelines, and with the links
generated by gi-docgen.
2024-01-15 14:43:53 +00:00
Simon McVittie
aa28326b87 docs: Allow building man pages without the reference documentation
Now that the reference documentation uses gi-docgen, it's more
troublesome to generate in less standard build scenarios like
cross-compiling.

In distributions like Debian, reference documentation is generally
packaged separately (in libglib2.0-doc in Debian's case), but man pages
are generally packaged alongside the executables themselves (in the
libglib2.0-bin and libglib2.0-dev-bin packages, in Debian's case). We
can exclude the reference documentation when cross-compiling, but ideally
we would like the man pages to still be built, so that a cross-compiled
libglib2.0-bin or libglib2.0-dev-bin package has the same content as a
native build.

Signed-off-by: Simon McVittie <smcv@debian.org>
2024-01-11 15:41:34 +00:00
Jordan Petridis
3f9f5c1420 docs: Fix links to symbols outside the allowed namsepace
Use markdown links for anything that the docs don't depend upon,
like gtk, pixbuf, etc
2024-01-09 21:24:22 +02:00
Philip Withnall
caf57bac0c docs: Drop outdated .gitignore files
These are no longer relevant since dropping gtk-doc.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2024-01-01 12:50:12 +00:00
Emmanuele Bassi
0db7395ef9 build: Tell gi-docgen where to find the GIR files
Now that all files are located under top_srcdir/introspection, we need
to ensure that gi-docgen can find them.
2023-12-27 16:00:06 +00:00
Emmanuele Bassi
cda15952dd Merge branch '3037-install-docs' into 'main'
docs: Install the gi-docgen docs

See merge request GNOME/glib!3787
2023-12-21 18:23:53 +00:00
Philip Withnall
d2dbfba208 docs: Install the gi-docgen docs
They are now installed to (e.g.)
`${prefix}/share/doc/glib-2.0/{glib,gmodule,gobject,gio}/index.html`.

We might want to drop one level of nesting out of that, but for the
moment I thought I’d keep it in so we can disambiguate by installed
major version.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2023-12-21 17:00:06 +00:00
Philip Withnall
031e65808d docs: Port the man pages from DocBook to reStructuredText
So they are consistent with the way we’re building man pages in other
projects, and because some people are allergic to XML.

This changes the build-time dependencies from `xsltproc` to `rst2man`,
and also takes the opportunity to change the `-Dman` Meson option from a
boolean to a feature (so you should use `-Dman-pages={enabled,disabled}`
now, rather than `-Dman={true,false}`).

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2023-12-21 13:34:48 +00:00
Philip Withnall
385641572d Merge branch '3037-docs-ci' into 'main'
ci: Build docs artifacts for deployment to docs.gtk.org

See merge request GNOME/glib!3768
2023-12-21 12:32:34 +00:00
Yegor Yefremov
b969e8fd58 docs: fix a typo
Fix a typo found with codespell.

Signed-off-by: Yegor Yefremov <yegorslists@googlemail.com>
2023-12-21 07:45:04 +01:00
Philip Withnall
9ea0b6edf5 docs: Set install_tag on man pages
Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2023-12-18 14:52:39 +00:00
Philip Withnall
11e46361ef docs: Add GIRepository documentation build using gi-docgen
Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3155
2023-12-12 16:58:04 +00:00
Emmanuele Bassi
9a2de39044 docs: Add a section on version checking macros
This is a port to GLib of changes originally made in the GTK copy of
these docs, at https://gitlab.gnome.org/GNOME/gtk/-/commit/72b0a4431d04.

(Copied across by Philip Withnall.)

Helps: #3037
2023-12-12 13:59:43 +00:00
Philip Withnall
d86da581e6 Merge branch 'main' into 'main'
Documentation only: Added clarification about GWeakNotify and removed ambiguous text

See merge request GNOME/glib!3739
2023-12-03 22:48:47 +00:00
madmurphy
abd7f9863d Documentation only: Added clarification about GWeakNotify and removed ambiguous text 2023-12-03 22:48:46 +00:00
Emmanuele Bassi
b53218a509 Merge branch '3037-doc-build-cleanups' into 'main'
build: Rename -Dgtk_doc option to -Ddocumentation and fix some g-ir-scanner warnings

See merge request GNOME/glib!3736
2023-12-01 22:48:17 +00:00
Philip Withnall
7b2ac3c82e docs: Consistently capitalise page titles
Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2023-11-29 12:13:13 +00:00
Philip Withnall
e8edaeeb87 build: Rename -Dgtk_doc option to -Ddocumentation
Because the documentation is no longer built using gtk-doc.

Keep the old option around, but deprecated.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2023-11-29 10:26:37 +00:00
Matthias Clasen
6ca2934928 build: Remove all remaining gtk-doc build infrastructure
It’s no longer needed: the documentation is built by gi-docgen now.

Fixes: #3037
2023-11-28 13:52:35 +00:00
Philip Withnall
0fe3a9d1df docs: Drop the tools tutorial page
It’s completely out of date.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2023-11-28 13:52:05 +00:00
Philip Withnall
54eb9b8900 docs: Convert the resources page to Markdown
And change mentions of ‘mailing lists’ to ‘support’ while I’m there.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2023-11-28 13:52:05 +00:00