Improve documentation

Signed-off-by: Aurélien Bompard <aurelien@bompard.org>
fedora-infra · Dec 21, 2022 · 1fa8998 · 1fa8998
1 parent 4228dd8
commit 1fa8998
Show file tree

Hide file tree

Showing 19 changed files with 111 additions and 72 deletions.
diff --git a/docs/api.rst → docs/api/api.rst b/docs/api.rst → docs/api/api.rst
diff --git a/docs/wire-format.rst → docs/api/wire-format.rst b/docs/wire-format.rst → docs/api/wire-format.rst
diff --git a/docs/build-schemas-list.py b/docs/build-schemas-list.py
@@ -16,7 +16,7 @@
 
 
 SCHEMAS_FILE = "schema-packages.txt"
-DOC_FILE = "schemas.rst"
+DOC_FILE = "user-guide/schemas.rst"
 HEADER = """
 =================
 Available Schemas

diff --git a/docs/conf.py b/docs/conf.py
@@ -89,9 +89,12 @@
 html_theme_options = {
     "github_user": "fedora-infra",
     "github_repo": "fedora-messaging",
+    "github_button": True,
+    "description": "A set of tools for using Fedora's messaging infrastructure",
     "page_width": "1040px",
     "show_related": True,
     "sidebar_collapse": True,
+    "caption_font_size": "150%",
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -154,7 +157,13 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ("fedora-messaging", "fedora-messaging", "Fedora Messaging CLI", [author], 1)
+    (
+        "user-guide/cli/fedora-messaging",
+        "fedora-messaging",
+        "Fedora Messaging CLI",
+        [author],
+        1,
+    )
 ]
 
 

diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -1,10 +1,11 @@
-============
-Contributing
-============
+=================
+Contributor guide
+=================
 
 Thanks for considering contributing to fedora-messaging, we really appreciate it!
 
-Quickstart:
+Quickstart
+==========
 
 1. Look for an `existing issue
    <https://github.com/fedora-infra/fedora-messaging/issues>`_ about the bug or
@@ -28,17 +29,15 @@ below.
 .. note:: If you do not wish to use GitHub, please send patches to
           infrastructure@lists.fedoraproject.org.
 
-Guidelines
-==========
 
 Python Support
---------------
+==============
 fedora-messaging supports Python 3.6 or greater. This is automatically enforced
 by the continuous integration (CI) suite.
 
 
 Code Style
-----------
+==========
 We follow the `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_ style guide
 for Python. This is automatically enforced by the CI suite.
 
@@ -51,7 +50,7 @@ To setup to hook for your repo clone, install pre-commit and run ``pre-commit in
 
 
 Tests
------
+=====
 The test suites can be run using `tox <http://tox.readthedocs.io/>`_ by simply
 running ``tox`` from the repository root. All code must have test coverage or
 be explicitly marked as not covered using the ``# no-qa`` comment. This should
@@ -62,8 +61,7 @@ you're not certain how to write tests, we will be happy to help you.
 
 
 Release notes
--------------
-
+=============
 To add entries to the release notes, run ``towncrier create <source.type>`` to
 create a news fragment file in the ``news`` directory, where ``type`` is one of:
 
@@ -99,8 +97,7 @@ A preview of the release notes can be generated with ``towncrier --draft``.
 
 
 Licensing
----------
-
+=========
 Your commit messages must include a Signed-off-by tag with your name and e-mail
 address, indicating that you agree to the `Developer Certificate of Origin
 <https://developercertificate.org/>`_ version 1.1::
@@ -147,8 +144,7 @@ Use ``git commit -s`` to add the Signed-off-by tag.
 
 
 Releasing
----------
-
+=========
 When cutting a new release, follow these steps:
 
 * update the version in ``fedora_messaging/__init__.py``

diff --git a/docs/index.rst b/docs/index.rst
@@ -12,58 +12,52 @@ This library is designed to be a replacement for the `PyZMQ`_-backed `fedmsg`_
 library.
 
 
-User Guide
-==========
-
 .. toctree::
    :maxdepth: 2
+   :caption: User Guide
 
-   installation
-   quick-start
-   configuration
-   publishing
-   consuming
-   messages
-   testing
-   schemas
-   changelog
-
+   user-guide/installation
+   user-guide/quick-start
+   user-guide/configuration
+   user-guide/publishing
+   user-guide/messages
+   user-guide/consuming
+   user-guide/schemas
+   user-guide/testing
+   user-guide/cli
 
-Command Line Interface Manuals
-------------------------------
 
 .. toctree::
    :maxdepth: 2
+   :caption: Tutorial
 
-   fedora-messaging
+   tutorial/installation
+   tutorial/usage
+   tutorial/schemas
+   tutorial/exceptions
+   tutorial/conversion
 
 
-Tutorial
-========
-
 .. toctree::
    :maxdepth: 2
+   :caption: API Documentation
 
-   tutorial/index
-
+   api/api
+   api/wire-format
 
-API Documentation
-=================
 
 .. toctree::
    :maxdepth: 2
+   :caption: Contributing
 
-   api
-   wire-format
-
+   contributing
 
-Contributor Guide
-=================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :caption: Release Notes
 
-   contributing
+   changelog
 
 
 .. _fedmsg: https://github.com/fedora-infra/fedmsg/

diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst
diff --git a/docs/user-guide/cli.rst b/docs/user-guide/cli.rst
@@ -0,0 +1,7 @@
+Command Line Interface Manuals
+------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   cli/fedora-messaging
diff --git a/docs/fedora-messaging.rst → docs/user-guide/cli/fedora-messaging.rst b/docs/fedora-messaging.rst → docs/user-guide/cli/fedora-messaging.rst
diff --git a/docs/configuration.rst → docs/user-guide/configuration.rst b/docs/configuration.rst → docs/user-guide/configuration.rst
diff --git a/docs/consuming.rst → docs/user-guide/consuming.rst b/docs/consuming.rst → docs/user-guide/consuming.rst
diff --git a/docs/installation.rst → docs/user-guide/installation.rst b/docs/installation.rst → docs/user-guide/installation.rst
diff --git a/docs/messages.rst → docs/user-guide/messages.rst b/docs/messages.rst → docs/user-guide/messages.rst
@@ -1,8 +1,8 @@
 .. _messages:
 
-========
-Messages
-========
+===============
+Message Schemas
+===============
 
 Before you release your application, you should create a subclass of
 :class:`fedora_messaging.message.Message`, define a schema, define a default
@@ -23,7 +23,8 @@ develop!
 
 Secondly, it allows you to change your message format in a controlled fashion
 by versioning your schema. You can then choose to implement methods one way or
-another based on the version of the schema used by a message.
+another based on the version of the schema used by a message. For details on how
+to deprecate and upgrade message schemas, see :ref:`schema-upgrade`.
 
 Message schema are defined using `JSON Schema`_. The complete API can be found
 in the :ref:`message-api` API documentation.
@@ -52,7 +53,7 @@ object.
 Example Schema
 --------------
 
-.. include:: sample_schema_package/mailman_messages/messages.py
+.. include:: ../sample_schema_package/mailman_messages/messages.py
    :literal:
 
 Note that message schema can be composed of other message schema, and
@@ -78,6 +79,52 @@ format. Messages should provide Python properties to access the deserialized
 JSON object. This Python API should maintain backwards compatibility between
 schema. This shields consumers from changes in schema.
 
+Useful Accessors
+~~~~~~~~~~~~~~~~
+
+All available accessors are described in the :ref:`message-api` API documentation ;
+here is a list of those we recommend implementing to allow users to get
+notifications for your messages:
+
+* :py:meth:`~fedora_messaging.message.Message.__str__`:
+  A human-readable representation of this message. This can be a multi-line string
+  that forms the body of an email notification.
+* :py:attr:`~fedora_messaging.message.Message.summary`:
+  A short, single-line, human-readable summary of the message, much like the subject
+  line of an email.
+* :py:attr:`~fedora_messaging.message.Message.agent_name`:
+  The username of the user who caused the action.
+* :py:attr:`~fedora_messaging.message.Message.app_name`:
+  The name of the application that generated the message. This can be implemented as
+  a class attribute or as a property.
+* :py:attr:`~fedora_messaging.message.Message.app_icon`:
+  A URL to the icon of the application that generated the message. This can be
+  implemented as a class attribute or as a property.
+* :py:attr:`~fedora_messaging.message.Message.packages`:
+  A list of RPM packages affected by the action that generated this message, if any.
+* :py:attr:`~fedora_messaging.message.Message.flatpaks`:
+  A list of flatpaks affected by the action that generated this message, if any.
+* :py:attr:`~fedora_messaging.message.Message.modules`:
+  A list of modules affected by the action that generated this message, if any.
+* :py:attr:`~fedora_messaging.message.Message.containers`:
+  A list of containers affected by the action that generated this message, if any.
+* :py:attr:`~fedora_messaging.message.Message.usernames`:
+  A list of usernames affected by the action that generated this message.
+  This may contain the ``agent_name``.
+* :py:attr:`~fedora_messaging.message.Message.groups`:
+  A list of group names affected by the action that generated this message.
+* :py:attr:`~fedora_messaging.message.Message.url`:
+  A URL to the action that caused this message to be emitted, if any.
+* :py:attr:`~fedora_messaging.message.Message.severity`:
+  An integer that indicates the severity of the message. This is used to determine
+  what messages to notify end users about and should be
+  :py:data:`~fedora_messaging.message.DEBUG`,
+  :py:data:`~fedora_messaging.message.INFO`,
+  :py:data:`~fedora_messaging.message.WARNING`,
+  or :py:data:`~fedora_messaging.message.ERROR`.
+  The default is :py:data:`~fedora_messaging.message.INFO`, and can be set
+  as a class attribute or on an instance-by-instance basis.
+
 
 Packaging
 =========
@@ -121,6 +168,8 @@ structure for you.
 
 
 
+.. _schema-upgrade:
+
 Upgrade and deprecation
 =======================
 

diff --git a/docs/publishing.rst → docs/user-guide/publishing.rst b/docs/publishing.rst → docs/user-guide/publishing.rst
diff --git a/docs/quick-start.rst → docs/user-guide/quick-start.rst b/docs/quick-start.rst → docs/user-guide/quick-start.rst
@@ -93,7 +93,7 @@ If fedora-messaging was installed via RPM, they should be in
 `key`_, `certificate`_, and the `CA certificate`_ from the upstream git
 repository and start with the following configuration file:
 
-.. literalinclude:: ../configs/fedora.toml
+.. literalinclude:: ../../configs/fedora.toml
 
 Assuming the ``/etc/fedora-messaging/fedora.toml``,
 ``/etc/fedora-messaging/cacert.pem``, ``/etc/fedora-messaging/fedora-key.pem``,

diff --git a/docs/schemas.rst → docs/user-guide/schemas.rst b/docs/schemas.rst → docs/user-guide/schemas.rst
diff --git a/docs/testing.rst → docs/user-guide/testing.rst b/docs/testing.rst → docs/user-guide/testing.rst
diff --git a/fedora_messaging/config.py b/fedora_messaging/config.py
@@ -27,7 +27,7 @@
 
 A complete example TOML configuration:
 
-.. literalinclude:: ../config.toml.example
+.. literalinclude:: ../../config.toml.example
 
 
 Generic Options

diff --git a/fedora_messaging/message.py b/fedora_messaging/message.py
@@ -587,8 +587,8 @@ def agent_name(self):
     def agent_avatar(self):
         """An URL to the avatar of the user who caused the action.
 
-        .. note:: Sub-classes should override this method if the message was
-            triggered by a particular user.
+        .. note:: Sub-classes should override this method if the default
+            Libravatar and OpenID-based URL generator is not appropriate.
 
         Returns:
             str or None: The URL to the user's avatar.