Sphinx based user documentation

The current output (more or less a straight copy of the wiki) is available
here:

https://gi.readthedocs.io

This contains two changes:

* Converts all (not completely outdated) wiki pages to a sphinx based
  documentation.
* Converts the man pages to reST and adds a Makefile for building them
  using rst2man. So they can be easily exposed in the sphinx docs.

Goals:

* Have a user focused/compact documentation instead of random wiki pages
  with various todo/ideas pages.
* Take advantage of the gitlab MR workflow by
  * allowing large documentation changes/refactorings with reviews
  * allowing to combine features changes with documentation changes in MRs

1 files changed, 137 insertions, 114 deletions

diff --git a/docs/g-ir-scanner.1 b/docs/g-ir-scanner.1
index d38241f1..2078d927 100644
--- a/docs/g-ir-scanner.1
+++ b/docs/g-ir-scanner.1
@@ -1,154 +1,177 @@
-.TH "g-ir-scanner" 1
-.nh
+.\" Man page generated from reStructuredText.
+.
+.TH G-IR-SCANNER 1 "" "" ""
 .SH NAME
-g-ir-scanner \- extracting C metadata from sources and headers
+g-ir-scanner \- Extracting C metadata from sources and headers
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
 .SH SYNOPSIS
-.B g-ir-scanner
-[OPTION...] FILES...
+.sp
+\fBg\-ir\-scanner\fP [OPTION...] FILES...
 .SH DESCRIPTION
-g-ir-scanner is a tool which generates GIR XML files by parsing headers
-and introspecting GObject based libraries.
-It is usually invoked during the normal build step for a project and
-the information is saved to disk and later installed, so that language bindings
-and other applications can use it.
-Header files and source files are passed in as arguments on the command line.
-The suffix determines whether a file be treated as a source file (.c) or a
-header file (.h). Currently only C based libraries are supported by the scanner.
+.sp
+g\-ir\-scanner is a tool which generates GIR XML files by parsing headers and
+introspecting GObject based libraries. It is usually invoked during the normal
+build step for a project and the information is saved to disk and later
+installed, so that language bindings and other applications can use it. Header
+files and source files are passed in as arguments on the command line. The
+suffix determines whether a file be treated as a source file (.c) or a header
+file (.h). Currently only C based libraries are supported by the scanner.
 .SH OPTIONS
+.INDENT 0.0
 .TP
-.B \--help
+.B \-\-help
 Show help options
 .TP
-.B \--quiet
+.B \-\-quiet
 If passed, do not print details of normal operation.
 .TP
-.B \--warn-all
+.B \-\-warn\-all
 Display warnings for public API which is not introspectable.
 .TP
-.B \--warn-error
+.B \-\-warn\-error
 Make warnings be fatal errors.
 .TP
-.B \--format=FORMAT
-This parameters decides which the resulting format will be used.
-The default value is gir.
+.BI \-\-format\fB= FORMAT
+This parameters decides which the resulting format will be used. The
+default value is gir.
 .TP
-.B \--include=NAME
+.BI \-\-include\fB= NAME
 Add the specified introspection dependency to the scanned namespace.
-NAME is of the form NAMESPACE-VERSION, like Gtk-3.0.
+NAME is of the form NAMESPACE\-VERSION, like Gtk\-3.0.
 .TP
-.B \--include-uninstalled=PATH
+.BI \-\-include\-uninstalled\fB= PATH
 Add the specified introspection dependency to the scanned namespace.
-This differs from \--include in that it takes a file path, and
-does not process the pkg-config dependencies (since they may not
-be installed yet).
+This differs from \fB\-\-include\fP in that it takes a file path, and does not
+process the pkg\-config dependencies (since they may not be installed yet).
 .TP
-.B \--add-include-path=PATH
-Add a directory to the path which the scanner uses to find GIR files.
-Can be used multiple times to specify multiple directories
+.BI \-\-add\-include\-path\fB= PATH
+Add a directory to the path which the scanner uses to find GIR files. Can
+be used multiple times to specify multiple directories
 .TP
-.B \-i, --library=LIBRARY
+.BI \-i\fP,\fB  \-\-library\fB= LIBRARY
 Specifies a library that will be introspected. This means that the
-*_get_type() functions in it will be called for GObject data types.
-The name of the library should not contain the leading lib prefix nor
-the ending shared library suffix.
+*_get_type() functions in it will be called for GObject data types. The
+name of the library should not contain the leading lib prefix nor the
+ending shared library suffix.
 .TP
-.B \-L, --library-path=PATH
-Include this directory when searching for a library.
-This option can be specified multiple times to include more than one
-directory to look for libraries in.
+.BI \-L\fP,\fB  \-\-library\-path\fB= PATH
+Include this directory when searching for a library. This option can be
+specified multiple times to include more than one directory to look for
+libraries in.
 .TP
-.B \-Idirectory
+.BI \-I\fB directory
 Include this directory in the list of directories to be searched for
-header files.  You need to pass to the scanner all the directories
-you'd normally pass to the compiler when using the specified source
-files.
+header files. You need to pass to the scanner all the directories you\(aqd
+normally pass to the compiler when using the specified source files.
 .TP
-.B \-n, --namespace=NAME
+.BI \-n\fP,\fB  \-\-namespace\fB= NAME
 The namespace name. This name should be capitalized, eg the first letter
 should be upper case. Examples: Gtk, Clutter, WebKit.
 .TP
-.B \--no-libtool
-Disable usage of libtool for compiling stub introspection binary.  Use this
+.B \-\-no\-libtool
+Disable usage of libtool for compiling stub introspection binary. Use this
 if your build system does not require libtool.
 .TP
-.B \--libtool
-Full path to libtool executable.  Typically used for Automake systems.
+.B \-\-libtool
+Full path to libtool executable. Typically used for Automake systems.
 .TP
-.B \--nsversion=VERSION
-The namespace version. For instance 1.0. This is usually the platform version,
-eg 2.0 for Gtk+, not 2.12.7.
+.BI \-\-nsversion\fB= VERSION
+The namespace version. For instance 1.0. This is usually the platform
+version, eg 2.0 for Gtk+, not 2.12.7.
 .TP
-.B \-p, --program=PROGRAM
+.BI \-p\fP,\fB  \-\-program\fB= PROGRAM
 Specifies a binary that will be introspected. This means that the
-*_get_type() functions in it will be called for GObject data types.
-The binary must be modified to take a --introspect-dump= option, and
-to pass the argument to this function to g_irepository_dump.
+*_get_type() functions in it will be called for GObject data types. The
+binary must be modified to take a \fB\-\-introspect\-dump=\fP option, and to pass
+the argument to this function to g_irepository_dump.
 .TP
-.B \--program-arg=ARG
+.BI \-\-program\-arg\fB= ARG
 Additional argument to pass to program for introspection.
 .TP
-.B \--identifier-prefix=PREFIX
-This option may be specified multiple times.  Each one
-gives a prefix that will be stripped from all C identifiers.
-If none specified, the namespace will be used.
-Eg, an identifier prefix of
-.B Foo
-will export the identifier
-.B typdef struct _FooBar FooBar;
-as
-.B Foo.Bar.
-.TP
-.B \--symbol-prefix=PREFIX
-This option may be specified multiple times.  Each one
-gives a prefix that will be stripped from all C symbols.
-Eg, an symbol prefix of
-.B foo
-will export the symbol
-.B foo_bar_do_something
-as
-.B Foo.Bar.do_something.
-.TP
-.B \--accept-unprefixed
-If specified, the scanner will accept identifiers and symbols which
-do not match the namespace prefix.  Try to avoid using this if possible.
-.TP
-.B \--output=FILENAME
-Name of the file to output. Normally namespace + format extension.
-Eg, GLib-2.0.gir.
-.TP
-.B \--pkg=PACKAGE
-List of pkg-config packages to get compiler and linker flags from.
-This option can be specified multiple times to include flags from
-several pkg-config packages.
-.TP
-.B \--pkg-export=PACKAGE
-List of pkg-config packages that are provided by the generated gir.
-This option can be specified multiple times if the gir provides more
-packages.
-If not specified, the packages specified with --pkg= will be used.
-.TP
-.B \--verbose
+.BI \-\-identifier\-prefix\fB= PREFIX
+This option may be specified multiple times. Each one gives a prefix that
+will be stripped from all C identifiers. If none specified, the namespace
+will be used. Eg, an identifier prefix of Foo will export the identifier
+typdef struct _FooBar FooBar; as Foo.Bar.
+.TP
+.BI \-\-symbol\-prefix\fB= PREFIX
+This option may be specified multiple times. Each one gives a
+prefix that will be stripped from all C symbols. Eg, an symbol
+prefix of foo will export the symbol foo_bar_do_something as
+Foo.Bar.do_something.
+.TP
+.B \-\-accept\-unprefixed
+If specified, the scanner will accept identifiers and symbols which do not
+match the namespace prefix. Try to avoid using this if possible.
+.TP
+.BI \-\-output\fB= FILENAME
+Name of the file to output. Normally namespace + format extension. Eg,
+GLib\-2.0.gir.
+.TP
+.BI \-\-pkg\fB= PACKAGE
+List of pkg\-config packages to get compiler and linker flags from. This
+option can be specified multiple times to include flags from several
+pkg\-config packages.
+.TP
+.BI \-\-pkg\-export\fB= PACKAGE
+List of pkg\-config packages that are provided by the generated gir. This
+option can be specified multiple times if the gir provides more packages.
+If not specified, the packages specified with \fB\-\-pkg=\fP will be used.
+.TP
+.B \-\-verbose
 Be verbose, include some debugging information.
-.TP
+.UNINDENT
 .SH ENVIRONMENT VARIABLES
-The g-ir-scanner uses the XDG_DATA_DIRS variable to check for dirs,
-the girs are located in XDG_DATA_DIRS/gir-1.0. It is normally
-set on a distribution so you shouldn't need to set it yourself.
-
-The variable GI_SCANNER_DISABLE_CACHE ensures that the scanner will
-not write cache data to $HOME.
-
-The variable GI_SCANNER_DEBUG can be used to debug issues in the build-system that
-involve g-ir-scanner. When it is set to 'save-temps', then g-ir-scanner will not remove
-temporary files and directories after it terminates.
-
-The variable GI_HOST_OS can be used to control the OS name on the
-host that runs the scanner. It has the same semantics as the Python
-os.name property.
+.sp
+The g\-ir\-scanner uses the \fBXDG_DATA_DIRS\fP variable to check for dirs, the
+girs are located in \fBXDG_DATA_DIRS/gir\-1.0\fP\&. It is normally set on a
+distribution so you shouldn\(aqt need to set it yourself.
+.sp
+The variable \fBGI_SCANNER_DISABLE_CACHE\fP ensures that the scanner will not
+write cache data to \fB$HOME\fP\&.
+.sp
+The variable \fBGI_SCANNER_DEBUG\fP can be used to debug issues in the
+build\-system that involve g\-ir\-scanner. When it is set to \fBsave\-temps\fP, then
+g\-ir\-scanner will not remove temporary files and directories after it
+terminates.
+.sp
+The variable \fBGI_HOST_OS\fP can be used to control the OS name on the host
+that runs the scanner. It has the same semantics as the Python \fBos.name\fP
+property.
 .SH BUGS
-Report bugs at https://gitlab.gnome.org/GNOME/gobject\-introspection/issues.
-.SH HOMEPAGE and CONTACT
-http://live.gnome.org/GObjectIntrospection
+.sp
+Report bugs at \fI\%https://gitlab.gnome.org/GNOME/gobject\-introspection/issues\fP
+.SH HOMEPAGE AND CONTACT
+.sp
+\fI\%http://live.gnome.org/GObjectIntrospection\fP
 .SH AUTHORS
+.sp
 Johan Dahlin
-
+.\" Generated by docutils manpage writer.
+.