Docs: Resolve various warnings.

TYPE: Bugfix
OneGov · Jul 11, 2024 · e45c8c8 · e45c8c8
1 parent d11dd89
commit e45c8c8
Show file tree

Hide file tree

Showing 38 changed files with 209 additions and 176 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -47,7 +47,7 @@
 ]
 
 intersphinx_mapping = {
-    "libres": ("http://libres.readthedocs.org/en/latest/", None)
+    "libres": ("https://libres.readthedocs.io/en/latest/", None)
 }
 
 autodoc_member_order = "bysource"

diff --git a/docs/modules.rst b/docs/modules.rst
@@ -150,7 +150,7 @@ OneGov Reservation
 
 Libres integration for OneGov Cloud. Libres is a python library to reserve stuff.
 
-`Libres Documentation <https://libres.readthedocs.org/en/latest/>`_
+`Libres Documentation <https://libres.readthedocs.io/en/latest/>`_
 
 OneGov Search
 ^^^^^^^^^^^^^

diff --git a/docs/org.rst b/docs/org.rst
@@ -91,7 +91,7 @@ Through Stripe we support payments in any module that supports formcode:
 * Reservations
 
 As Stripe is just a payment provider, we are able to add additional payment
-providers, though it is certainly a lot of work. 
+providers, though it is certainly a lot of work.
 
 User-Management
 ^^^^^^^^^^^^^^^

diff --git a/src/onegov/activity/iso20022.py b/src/onegov/activity/iso20022.py
@@ -182,9 +182,9 @@ def match_iso_20022_to_usernames(
     Raises an error if the given xml cannot be processed.
 
     :return: An iterator of transactions found in the xml file, together with
-    the matching username and a confidence attribute indicating how
-    certain the match is (1.0 indicating a sure match, 0.5 a possible match
-    and 0.0 a non-match).
+        the matching username and a confidence attribute indicating how
+        certain the match is (1.0 indicating a sure match, 0.5 a possible match
+        and 0.0 a non-match).
 
     """
 

diff --git a/src/onegov/agency/api.py b/src/onegov/agency/api.py
@@ -40,7 +40,7 @@ def filter_for_updated(
     Refer to UPDATE_FILTER_PARAMS for all filter keywords.
 
     :param filter_operation: the updated filter operation to be applied. For
-    allowed filters refer to UPDATE_FILTER_PARAMS
+        allowed filters refer to UPDATE_FILTER_PARAMS
     :param filter_value: the updated filter value to filter for
     :param result: the results to apply the filters on
     :return: filter result

diff --git a/src/onegov/api/models.py b/src/onegov/api/models.py
@@ -286,7 +286,8 @@ def batch(self) -> dict['ApiEndpointItem[_M]', _M]:
     def item_data(self, item: _M) -> dict[str, Any]:
         """ Return the data properties of the collection item as a dictionary.
 
-        For example:
+        For example::
+
             {
                 'name': 'Paul',
                 'age': 40
@@ -300,7 +301,8 @@ def item_links(self, item: _M) -> dict[str, Any]:
         """ Return the link properties of the collection item as a dictionary.
         Links can either be string or a linkable object.
 
-        For example:
+        For example::
+
             {
                 'website': 'https://onegov.ch',
                 'friends': FriendsApiEndpoint(app).for_item(paul),

diff --git a/src/onegov/chat/utils.py b/src/onegov/chat/utils.py
@@ -10,7 +10,8 @@ def param_from_path(name: str, path: str) -> str:
     name are not supported and will result in ValueError, as it hints to a
     misconfiguration.
 
-    Example:
+    Example::
+
         >>> schema_from_path("schema", "/chats?schema=onegov_town6-meggen")
         'onegov_town6-meggen
 

diff --git a/src/onegov/core/cli/commands.py b/src/onegov/core/cli/commands.py
@@ -162,7 +162,9 @@ def sendmail(group_context: 'GroupContext', queue: str, limit: int) -> None:
 def sendsms(
     group_context: 'GroupContext'
 ) -> 'Callable[[CoreRequest, Framework], None]':
-    """ Sends the SMS in the smsdir for a given instance. For example:
+    """ Sends the SMS in the smsdir for a given instance.
+
+    For example::
 
         onegov-core --select '/onegov_town6/meggen' sendsms
 
@@ -227,7 +229,7 @@ def sms_spooler(group_context: 'GroupContext') -> None:
     """ Continuously spools the SMS in the smsdir for all instances using
     a watchdog that monitors the smsdir for newly created files.
 
-    For example:
+    For example::
 
         onegov-core sms-spooler
     """
@@ -326,8 +328,8 @@ def transfer(
     So if you have a 'cities' namespace locally and a 'towns' namespace on
     the remote, nothing will happen.
 
-    It's also possible to transfer only a given schema, e.g. '/town6/govikon'
-    or '/town6/*'. But beware, global files are copied in any case!
+    It's also possible to transfer only a given schema, e.g. ``/town6/govikon``
+    or ``/town6/*``. But beware, global files are copied in any case!
 
     WARNING: This may delete local content!
 

diff --git a/src/onegov/core/csv.py b/src/onegov/core/csv.py
@@ -757,7 +757,8 @@ def has_duplicates(a_list: 'Sequence[Any]') -> bool:
 def list_duplicates_index(a: 'Sequence[Any]') -> list[int]:
     """
         returns a list of indexes of duplicates in a list.
-        for example:
+        for example::
+
             a = [1, 2, 3, 2, 1, 5, 6, 5, 5, 5]
             list_duplicates_index(a) == [3, 4, 7, 8, 9]
     """

diff --git a/src/onegov/core/orm/abstract/associable.py b/src/onegov/core/orm/abstract/associable.py
@@ -39,7 +39,7 @@
 Here, ``Payment`` is associable (through the ``Payable`` mixin).
 ``Reservation`` and ``Form`` in turn inherit from ``Payable``.
 
-This all is probably best understood in an example:
+This all is probably best understood in an example::
 
         class Payment(Base, Associable):
             __tablename__ == 'payments'

diff --git a/src/onegov/core/orm/cache.py b/src/onegov/core/orm/cache.py
@@ -63,7 +63,7 @@ def __call__(
 
 class OrmCacheApp:
     """ Integrates the orm cache handling into the application
-    (i.e. :class:`onegov.core.framework.Framework').
+    (i.e. :class:`onegov.core.framework.Framework`).
 
     In addition, the application needs to call :meth:`setup_orm_cache` inside
     of `:meth:onegov.server.application.Application.set_application_id` to

diff --git a/src/onegov/core/request.py b/src/onegov/core/request.py
@@ -544,7 +544,7 @@ def message(self, text: str, type: 'MessageType') -> None:
         messages list may then be displayed by an application building on
         onegov.core.
 
-        For example:
+        For example::
 
             http://foundation.zurb.com/docs/components/alert_boxes.html
 

diff --git a/src/onegov/core/utils.py b/src/onegov/core/utils.py
@@ -1047,13 +1047,13 @@ def yubikey_otp_to_serial(otp: str) -> int | None:
 
     The serial key is printed on the yubikey, in decimal and as a QR code.
 
-    Example:
+    Example::
 
         >>> yubikey_otp_to_serial(
             'ccccccdefghdefghdefghdefghdefghdefghdefghklv')
         2311522
 
-    Adapted from Java:
+    Adapted from Java::
 
         https://github.com/Yubico/yubikey-salesforce-client/blob/
         e38e46ee90296a852374a8b744555e99d16b6ca7/src/classes/Modhex.cls
@@ -1103,7 +1103,9 @@ def yubikey_public_id(otp: str) -> str:
 
 
 def dict_path(dictionary: dict[str, _T], path: str) -> _T:
-    """ Gets the value of the given dictionary at the given path. For example:
+    """ Gets the value of the given dictionary at the given path.
+
+    For example::
 
         >>> data = {'foo': {'bar': True}}
         >>> dict_path(data, 'foo.bar')

diff --git a/src/onegov/election_day/utils/archive_generator.py b/src/onegov/election_day/utils/archive_generator.py
@@ -52,20 +52,20 @@ def __init__(self, app: 'ElectionDayApp'):
 
     def generate_csv(self) -> None:
         """
-        Creates csv files with a directory structure like this:
-
-        archive
-        ├── elections
-        │        └── 2022
-        │             ├── election1.csv
-        │             ├── election2.csv
-        │             └── ...
-        │
-        └── votes
-            ├── 2021
-            │   └── vote1.csv
-            └── 2022
-                └── vote1.csv
+        Creates csv files with a directory structure like this::
+
+            archive
+            ├── elections
+            │        └── 2022
+            │             ├── election1.csv
+            │             ├── election2.csv
+            │             └── ...
+            │
+            └── votes
+                ├── 2021
+                │   └── vote1.csv
+                └── 2022
+                    └── vote1.csv
 
         """
 
@@ -137,11 +137,11 @@ def zip_dir(self, base_dir: 'SubFS[FS]') -> str | None:
         """Recursively zips a directory (base_dir).
 
         :param base_dir: is a directory in a temporary file system.
-        Contains subdirectories 'votes' and 'elections', as well as various
-        other files to include.
+            Contains subdirectories 'votes' and 'elections', as well as various
+            other files to include.
 
         :returns path to the zipfile or None if base_dir doesn't exist
-        or is empty.
+            or is empty.
         """
         self.archive_dir.makedir(self.archive_parent_dir, recreate=True)
         zip_path = f'{self.archive_parent_dir}/archive.zip'

diff --git a/src/onegov/election_day/utils/election/candidates.py b/src/onegov/election_day/utils/election/candidates.py
@@ -135,10 +135,11 @@ def get_candidates_data(
     """" Get the candidates as JSON. Used to for the candidates bar chart.
 
     Allows to optionally
-    - return only the first ``limit`` results.
-    - return only results for candidates within the given list names (proporz)
+
+    * return only the first ``limit`` results.
+    * return only results for candidates within the given list names (proporz)
       or party names (majorz).
-    - return only elected candidates. If not specified, only elected candidates
+    * return only elected candidates. If not specified, only elected candidates
       are returned for proporz elections, all for majorz elections.
 
     """

diff --git a/src/onegov/event/collections/events.py b/src/onegov/event/collections/events.py
@@ -480,45 +480,46 @@ def as_anthrazit_xml(
         """
         Returns all published occurrences as xml for Winterthur.
         Anthrazit format according
-        https://doc.anthrazit.org/ext/XML_Schnittstelle
-
-        <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-        <import partner="???" partnerid"???" passwort"???" importid="??">
-            <item status="1" suchbar="1" mutationsdatum="2023-08-18 08:23:30">
-                <id>01</id>
-                <titel>Titel der Seite</titel>
-                <textmobile>2-3 Sätze des Text Feldes packed in
-                CDATA</textmobile>
-                <termin allday="1">
-                    <von>2011-08-06 00:00:00</von>
-                    <bis>2011-08-06 23:59:00</bis>
-                </termin>
-                <termin>
+        https://doc.anthrazit.org/ext/XML_Schnittstelle::
+
+            <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+            <import partner="???" partnerid"???" passwort"???" importid="??">
+                <item status="1" suchbar="1"
+                      mutationsdatum="2023-08-18 08:23:30">
+                    <id>01</id>
+                    <titel>Titel der Seite</titel>
+                    <textmobile>2-3 Sätze des Text Feldes packed in
+                    CDATA</textmobile>
+                    <termin allday="1">
+                        <von>2011-08-06 00:00:00</von>
+                        <bis>2011-08-06 23:59:00</bis>
+                    </termin>
+                    <termin>
+                        ...
+                    </termin>
+                    <url_web>url</url_web>
+                    <url_bild>bild</url_bild>
+                    <hauptrubrik name="Naturmusuem">
+                        <rubrik>tag_1</rubrik>
+                        <rubrik>tag_2</rubrik>
+                    </hauptrubrik>
+                    <email></email>
+                    <telefon1></telefon1>
+                    <sf01>Veranstaltungspreis packed in CDATA</sf01>
+                    <veranstaltungsort>
+                        <title></title>
+                        <longitude></longitude>
+                        <latitude></latitude>
+                    </veranstaltungsort>
                     ...
-                </termin>
-                <url_web>url</url_web>
-                <url_bild>bild</url_bild>
-                <hauptrubrik name="Naturmusuem">
-                    <rubrik>tag_1</rubrik>
-                    <rubrik>tag_2</rubrik>
-                </hauptrubrik>
-                <email></email>
-                <telefon1></telefon1>
-                <sf01>Veranstaltungspreis packed in CDATA</sf01>
-                <veranstaltungsort>
-                    <title></title>
-                    <longitude></longitude>
-                    <latitude></latitude>
-                </veranstaltungsort>
-                ...
-            </item>
-            <item>
-                ...
-            </item>
-        </import>
+                </item>
+                <item>
+                    ...
+                </item>
+            </import>
 
         :param future_events_only: if set, only future events will be
-        returned, all events otherwise
+            returned, all events otherwise
         :rtype: str
         :return: xml string
 

diff --git a/src/onegov/event/collections/occurrences.py b/src/onegov/event/collections/occurrences.py
@@ -621,30 +621,31 @@ def as_xml(self, future_events_only: bool = True) -> bytes:
         Returns all published occurrences as xml.
 
         The xml format was Winterthur's wish (no specs behind). Their mobile
-        app will consume the events from xml
-
-        Format:
-        <events>
-            <event>
-                <id></id>
-                <title></title>
-                <tags></tags>
-                    <tag></tag>
-                <description></description>
-                <start></start>
-                <end></end>
-                <location></location>
-                <price></price>
+        app will consume the events from.
+
+        Format::
+
+            <events>
+                <event>
+                    <id></id>
+                    <title></title>
+                    <tags></tags>
+                        <tag></tag>
+                    <description></description>
+                    <start></start>
+                    <end></end>
+                    <location></location>
+                    <price></price>
+                    ..
+                </event>
+                <event>
+                    ..
+                </event>
                 ..
-            </event>
-            <event>
-                ..
-            </event>
-            ..
-        </events>
+            </events>
 
         :param future_events_only: if set, only future events will be
-        returned, all events otherwise
+            returned, all events otherwise
         :rtype: str
         :return: xml string