[gtk/ebassi/howto-docs: 4/5] Add the beginnings of a docs contribution guide

[Emmanuele Bassi <ebassi src gnome org>]

commit c5485cd6b165dee558d942b0c847ac3ce83885bf
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Wed May 27 13:26:39 2020 +0100

    Add the beginnings of a docs contribution guide
    
    We have one for the whole project, but the documentation should have a
    proper introduction and a proper style guide.

 docs/reference/README.md | 150 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 150 insertions(+)
---
diff --git a/docs/reference/README.md b/docs/reference/README.md
new file mode 100644
index 0000000000..7cf169e799
--- /dev/null
+++ b/docs/reference/README.md
@@ -0,0 +1,150 @@
+# How to contribute to GTK's documentation
+
+The GTK documentation is divided in two major components:
+
+ - the API reference, which is generated from special comments in the GTK
+   source code
+ - static pages that provide an overview of specific sections of the API
+
+In both cases, the contents are parsed, converted into DocBook format, and
+cross-linked in order to match types, functions, signals, and properties.
+From the DocBook output, we generate HTML, which can be used to read the
+documentation both off line and online.
+
+In both cases, contributing to the GTK documentation requires modifying
+files tracked in the source control repository, and follows the same steps
+as any other code contribution as outlined in the GTK [contribution
+guide][contributing]. Please, refer to that document for any further
+question on the mechanics of contributing to GTK.
+
+GTK uses [gtk-doc][gtkdoc] to generate its documentation. Please, visit the
+gtk-doc website to read the project's documentation.
+
+[contributing]: ../../CONTRIBUTING.md
+[gtkdoc]: https://wiki.gnome.org/DocumentationProject/GtkDoc
+
+## Contributing to the API reference
+
+Whenever you need to add or modify the documentation of a type or a
+function, you will need to edit a `gtk-doc` comment stanza, typically right
+above the type or function declaration. For instance:
+
+```c
+/**
+ * gtk_foo_set_bar:
+ * @self: a #GtkFoo
+ * @bar: a #GtkBar
+ *
+ * Sets the given #GtkBar instance on a #GtkFoo widget.
+ */
+void
+gtk_foo_set_bar (GtkFoo *self,
+                GtkBar *bar)
+{
+  ...
+```
+
+Or, for types:
+
+```c
+/**
+ * GtkFoo:
+ *
+ * A foo widget instance.
+ *
+ * The contents of this structure are private and should never
+ * be accessed directly.
+ */
+struct _GtkFoo
+{
+  GtkWidget parent_instance;
+};
+```
+
+Each public function and type in the GTK API reference must be listed in the
+`sections.txt` file for the specific namespace to which it belongs: GDK,
+GSK, or GTK. For instance, if you add a function named `gtk_foo_set_bar()`,
+you will need to:
+
+ 1. open `docs/reference/gtk/gtk4-sections.txt`
+ 1. find the section that lists the symbols of the `GtkFoo` type
+ 1. add `gtk_foo_set_bar` to the list
+
+New classes require:
+
+ 1. a new section in the `sections.txt` file
+ 1. the `get_type` function added to the `.types` file
+ 1. an `xinclude` element in the `docs.xml` file
+
+## Style guide
+
+Like the [coding style][coding], these rules try to formalize the existing
+documentation style; in general, you should only ever modify existing code
+that does not match the rules if you're already changing that code for
+unrelated reasons.
+
+[coding]: ../CODING-STYLE.md
+
+### Sections
+
+ - The "section" of each type must contain a name, to be referenced in the
+   `sections.txt` file; a title; and a short description. For instance:
+
+```c
+/**
+ * SECTION:gtkshortcut
+ * @Title: GtkShortcut
+ * @Short_desc: A key shortcut
+ *
+ * ...
+```
+
+   For classes, the title should be the name of the class. While it's
+   possible to add section titles directly to the `sections.txt` file, this
+   is considered deprecated, and should not be done for newly written code.
+ - For classes, the long description should contain an overview of the type;
+   what it does; typical use cases; and idiomatic examples of its use.
+ - For widget classes, the long description of a section should also contain:
+   - special XML elements and attributes parsed by the class, in case of a
+     custom GtkBuildable implementation
+   - the CSS element name to be used by selectors
+   - the CSS selector hierarchy for children, in case of a composite widget
+
+### Functions
+
+ - The argument names must match in the declaration, definition, and
+   documentation stanza.
+ - The description should refer to the function as the subject, e.g.:
+
+```
+Adds a shortcut to the shortcuts controller.
+```
+
+   Or:
+
+```
+Checks whether the widget is set to be visible or not.
+```
+
+### Methods
+
+ - Methods are special functions whose first argument is always the instance
+   of a certain class. The instance argument for newly written code should be
+   called `self`.
+ - If a method is a setter or a getter for an object property, link the
+   property in the methods's description.
+ - If a method changes one or more properties as side effect, link those
+   properties in the method's description
+ - If a method is a signal emitter, link the signal in the method's
+   description.
+
+### Properties
+
+ - While GObject properties contain text that can be extracted
+   programmatically in order to build their documentation, you should
+   *always* document them with an explicit gtk-doc stanza. The text
+   associated to the property is short and meant to be used when
+   programmatically building user interfaces, and not for documentation
+   purposes.
+ - Always note if setting a property has side effects, like causing another
+   property to change state.