Allow to mention forums. (#288)

ansible-community · Jul 5, 2024 · 421ed2f · 421ed2f
1 parent 9163ac8
commit 421ed2f
Show file tree

Hide file tree

Showing 21 changed files with 56 additions and 2 deletions.
diff --git a/changelogs/fragments/288-forum.yml b/changelogs/fragments/288-forum.yml
@@ -0,0 +1,2 @@
+minor_changes:
+  - "Allow to mention forums in the Communication section of collection links (https://github.com/ansible-community/antsibull-docs/pull/288)."
diff --git a/docs/collection-docs.md b/docs/collection-docs.md
@@ -202,7 +202,7 @@ If you want to reference modules, plugins, roles, their options and return value
 
 You can add general links of interest to your collection page and the plugin pages, like for example links pointing to how to submit a bug report, how to request a feature, or where to ask for help. You can also provide links to communication channels like Matrix rooms, IRC channels, and mailing lists.
 
-These can be configured in `docs/docsite/links.yml`. A template showing what is available can be found in the [collection_template repository](https://github.com/ansible-collections/collection_template/blob/main/docs/docsite/links.yml).
+These can be configured in `docs/docsite/links.yml`. A template showing what is available can be found below:
 
 ```yaml
 ---
@@ -250,6 +250,10 @@ communication:
       # You can also add a `subscribe` field with an URI that allows to subscribe
       # to the mailing list. For lists on https://groups.google.com/ a subscribe link is
       # automatically generated.
+  forums:
+    - topic: Ansible Forum
+      # The following URL directly points to the "Get Help" section
+      url: https://forum.ansible.com/c/help/6/none
 ```
 
 ## Publishing a docsite with GitHub Actions

diff --git a/src/antsibull_docs/collection_links.py b/src/antsibull_docs/collection_links.py
@@ -70,6 +70,12 @@
                 "url": "https://groups.google.com/g/ansible-project",
             }
         ],
+        "forums": [
+            {
+                "topic": "Ansible Forum",
+                "url": "https://forum.ansible.com/c/help/6/none",
+            }
+        ],
     },
 }
 

diff --git a/src/antsibull_docs/data/docsite/ansible-docsite/plugins_by_collection.rst.j2 b/src/antsibull_docs/data/docsite/ansible-docsite/plugins_by_collection.rst.j2
@@ -80,6 +80,9 @@ Description
 Communication
 -------------
 
+{%   for forum in collection_communication.forums %}
+- Forum: `@{ forum.topic | rst_escape }@ <@{ forum.url | rst_escape }@>`__.
+{%   endfor %}
 {%   for matrix_room in collection_communication.matrix_rooms %}
 - Matrix room :literal:`@{ matrix_room.room | rst_escape(escape_ending_whitespace=true) }@`: `@{ matrix_room.topic | rst_escape }@ <https://matrix.to/#/@{ matrix_room.room | rst_escape }@>`__.
 {%   endfor %}

diff --git a/src/antsibull_docs/data/docsite/simplified-rst/plugins_by_collection.rst.j2 b/src/antsibull_docs/data/docsite/simplified-rst/plugins_by_collection.rst.j2
@@ -61,6 +61,9 @@ Collection links
 Communication
 -------------
 
+{%   for forum in collection_communication.forums %}
+- Forum: `@{ forum.topic | rst_escape }@ <@{ forum.url | rst_escape }@>`__.
+{%   endfor %}
 {%   for matrix_room in collection_communication.matrix_rooms %}
 - Matrix room :literal:`@{ matrix_room.room | rst_escape(escape_ending_whitespace=true) }@`: `@{ matrix_room.topic | rst_escape }@ <https://matrix.to/#/@{ matrix_room.room | rst_escape }@>`__.
 {%   endfor %}

diff --git a/src/antsibull_docs/schemas/collection_links.py b/src/antsibull_docs/schemas/collection_links.py
@@ -77,15 +77,24 @@ def add_subscribe(cls, values):
         return values
 
 
+class Forum(p.BaseModel):
+    topic: str
+    url: str
+
+
 class Communication(p.BaseModel):
     irc_channels: list[IRCChannel] = []
     matrix_rooms: list[MatrixRoom] = []
     mailing_lists: list[MailingList] = []
+    forums: list[Forum] = []
 
     @property
     def empty(self):
         return (
-            not self.irc_channels and not self.matrix_rooms and not self.mailing_lists
+            not self.irc_channels
+            and not self.matrix_rooms
+            and not self.mailing_lists
+            and not self.forums
         )
 
 

diff --git a/tests/functional/baseline-default/collections/ns2/col/index.rst b/tests/functional/baseline-default/collections/ns2/col/index.rst
@@ -57,6 +57,7 @@ With multiple paragraphs.
 Communication
 -------------
 
+- Forum: `Ansible Forum <https://forum.ansible.com/>`__.
 - Matrix room :literal:`#users:ansible.im`: `General usage and support questions <https://matrix.to/#/#users:ansible.im>`__.
 - IRC channel :literal:`#ansible` (Libera network):
   `General usage and support questions <https://web.libera.chat/?channel=#ansible>`__.

diff --git a/tests/functional/baseline-default/collections/ns2/flatcol/index.rst b/tests/functional/baseline-default/collections/ns2/flatcol/index.rst
@@ -38,6 +38,7 @@ Description
 Communication
 -------------
 
+- Forum: `Ansible Forum <https://forum.ansible.com/c/help/6/none>`__.
 - Matrix room :literal:`#users:ansible.im`: `General usage and support questions <https://matrix.to/#/#users:ansible.im>`__.
 - IRC channel :literal:`#ansible` (Libera network):
   `General usage and support questions <https://web.libera.chat/?channel=#ansible>`__.

diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/index.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/index.rst
@@ -58,6 +58,7 @@ With multiple paragraphs.
 Communication
 -------------
 
+- Forum: `Ansible Forum <https://forum.ansible.com/>`__.
 - Matrix room :literal:`#users:ansible.im`: `General usage and support questions <https://matrix.to/#/#users:ansible.im>`__.
 - IRC channel :literal:`#ansible` (Libera network):
   `General usage and support questions <https://web.libera.chat/?channel=#ansible>`__.

diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/index.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/index.rst
@@ -39,6 +39,7 @@ Description
 Communication
 -------------
 
+- Forum: `Ansible Forum <https://forum.ansible.com/c/help/6/none>`__.
 - Matrix room :literal:`#users:ansible.im`: `General usage and support questions <https://matrix.to/#/#users:ansible.im>`__.
 - IRC channel :literal:`#ansible` (Libera network):
   `General usage and support questions <https://web.libera.chat/?channel=#ansible>`__.

diff --git a/tests/functional/baseline-no-indexes/collections/ns2/col/index.rst b/tests/functional/baseline-no-indexes/collections/ns2/col/index.rst
@@ -57,6 +57,7 @@ With multiple paragraphs.
 Communication
 -------------
 
+- Forum: `Ansible Forum <https://forum.ansible.com/>`__.
 - Matrix room :literal:`#users:ansible.im`: `General usage and support questions <https://matrix.to/#/#users:ansible.im>`__.
 - IRC channel :literal:`#ansible` (Libera network):
   `General usage and support questions <https://web.libera.chat/?channel=#ansible>`__.

diff --git a/tests/functional/baseline-no-indexes/collections/ns2/flatcol/index.rst b/tests/functional/baseline-no-indexes/collections/ns2/flatcol/index.rst
@@ -38,6 +38,7 @@ Description
 Communication
 -------------
 
+- Forum: `Ansible Forum <https://forum.ansible.com/c/help/6/none>`__.
 - Matrix room :literal:`#users:ansible.im`: `General usage and support questions <https://matrix.to/#/#users:ansible.im>`__.
 - IRC channel :literal:`#ansible` (Libera network):
   `General usage and support questions <https://web.libera.chat/?channel=#ansible>`__.

diff --git a/tests/functional/baseline-simplified-rst-squash-hierarchy/index.rst b/tests/functional/baseline-simplified-rst-squash-hierarchy/index.rst
@@ -40,6 +40,7 @@ Collection links
 Communication
 -------------
 
+- Forum: `Ansible Forum <https://forum.ansible.com/>`__.
 - Matrix room :literal:`#users:ansible.im`: `General usage and support questions <https://matrix.to/#/#users:ansible.im>`__.
 - IRC channel :literal:`#ansible` (Libera network):
   `General usage and support questions <https://web.libera.chat/?channel=#ansible>`__.

diff --git a/tests/functional/baseline-simplified-rst/collections/ns2/col/index.rst b/tests/functional/baseline-simplified-rst/collections/ns2/col/index.rst
@@ -40,6 +40,7 @@ Collection links
 Communication
 -------------
 
+- Forum: `Ansible Forum <https://forum.ansible.com/>`__.
 - Matrix room :literal:`#users:ansible.im`: `General usage and support questions <https://matrix.to/#/#users:ansible.im>`__.
 - IRC channel :literal:`#ansible` (Libera network):
   `General usage and support questions <https://web.libera.chat/?channel=#ansible>`__.

diff --git a/tests/functional/baseline-simplified-rst/collections/ns2/flatcol/index.rst b/tests/functional/baseline-simplified-rst/collections/ns2/flatcol/index.rst
@@ -27,6 +27,7 @@ Collection links
 Communication
 -------------
 
+- Forum: `Ansible Forum <https://forum.ansible.com/c/help/6/none>`__.
 - Matrix room :literal:`#users:ansible.im`: `General usage and support questions <https://matrix.to/#/#users:ansible.im>`__.
 - IRC channel :literal:`#ansible` (Libera network):
   `General usage and support questions <https://web.libera.chat/?channel=#ansible>`__.

diff --git a/tests/functional/baseline-squash-hierarchy/index.rst b/tests/functional/baseline-squash-hierarchy/index.rst
@@ -57,6 +57,7 @@ With multiple paragraphs.
 Communication
 -------------
 
+- Forum: `Ansible Forum <https://forum.ansible.com/>`__.
 - Matrix room :literal:`#users:ansible.im`: `General usage and support questions <https://matrix.to/#/#users:ansible.im>`__.
 - IRC channel :literal:`#ansible` (Libera network):
   `General usage and support questions <https://web.libera.chat/?channel=#ansible>`__.

diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/index.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/index.rst
@@ -57,6 +57,7 @@ With multiple paragraphs.
 Communication
 -------------
 
+- Forum: `Ansible Forum <https://forum.ansible.com/>`__.
 - Matrix room :literal:`#users:ansible.im`: `General usage and support questions <https://matrix.to/#/#users:ansible.im>`__.
 - IRC channel :literal:`#ansible` (Libera network):
   `General usage and support questions <https://web.libera.chat/?channel=#ansible>`__.

diff --git a/tests/functional/collections/ansible_collections/ns/col2/docs/docsite/links.yml b/tests/functional/collections/ansible_collections/ns/col2/docs/docsite/links.yml
@@ -21,5 +21,7 @@ communication:
       network: true
   mailing_lists:
     - Ansible Project List
+  forums:
+    - topic: foo
 
 bla:
diff --git a/tests/functional/collections/ansible_collections/ns2/col/docs/docsite/links.yml b/tests/functional/collections/ansible_collections/ns2/col/docs/docsite/links.yml
@@ -23,3 +23,7 @@ communication:
   mailing_lists:
     - topic: Ansible Project List
       url: https://groups.google.com/g/ansible-project
+      subscribe: ansible-project+subscribe@googlegroups.com?subject=subscribe
+  forums:
+    - topic: Ansible Forum
+      url: https://forum.ansible.com/
diff --git a/tests/functional/collections/ansible_collections/ns2/flatcol/docs/docsite/links.yml b/tests/functional/collections/ansible_collections/ns2/flatcol/docs/docsite/links.yml
@@ -48,3 +48,6 @@ communication:
       # You can also add a `subscribe` field with an URI that allows to subscribe
       # to the mailing list. For lists on https://groups.google.com/ a subscribe link is
       # automatically generated.
+  forums:
+    - topic: Ansible Forum
+      url: https://forum.ansible.com/c/help/6/none
diff --git a/tests/functional/test_docs_linting.py b/tests/functional/test_docs_linting.py
@@ -195,6 +195,7 @@ def test_docsite_linting_failure(tmp_path_factory):
             'docs/docsite/extra-docs.yml:0:0: Section #1 has no "title" entry',
             "docs/docsite/extra-docs.yml:0:0: Toctree entry in section #0 is not a list",
             "docs/docsite/links.yml:0:0: bla: extra fields not permitted (type=value_error.extra)",
+            "docs/docsite/links.yml:0:0: communication -> forums -> 0 -> url: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> irc_channels -> 0 -> channel: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> mailing_lists -> 0: value is not a valid dict (type=type_error.dict)",
             "docs/docsite/links.yml:0:0: communication -> matrix_rooms: value is not a valid list (type=type_error.list)",
@@ -273,6 +274,7 @@ def test_docsite_linting_failure(tmp_path_factory):
             'docs/docsite/extra-docs.yml:0:0: Section #1 has no "title" entry',
             "docs/docsite/extra-docs.yml:0:0: Toctree entry in section #0 is not a list",
             "docs/docsite/links.yml:0:0: bla: extra fields not permitted (type=value_error.extra)",
+            "docs/docsite/links.yml:0:0: communication -> forums -> 0 -> url: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> irc_channels -> 0 -> channel: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> mailing_lists -> 0: value is not a valid dict (type=type_error.dict)",
             "docs/docsite/links.yml:0:0: communication -> matrix_rooms: value is not a valid list (type=type_error.list)",
@@ -371,6 +373,7 @@ def test_docsite_linting_failure(tmp_path_factory):
             'docs/docsite/extra-docs.yml:0:0: Section #1 has no "title" entry',
             "docs/docsite/extra-docs.yml:0:0: Toctree entry in section #0 is not a list",
             "docs/docsite/links.yml:0:0: bla: extra fields not permitted (type=value_error.extra)",
+            "docs/docsite/links.yml:0:0: communication -> forums -> 0 -> url: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> irc_channels -> 0 -> channel: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> mailing_lists -> 0: value is not a valid dict (type=type_error.dict)",
             "docs/docsite/links.yml:0:0: communication -> matrix_rooms: value is not a valid list (type=type_error.list)",
@@ -477,6 +480,7 @@ def test_docsite_linting_failure(tmp_path_factory):
             'docs/docsite/extra-docs.yml:0:0: Section #1 has no "title" entry',
             "docs/docsite/extra-docs.yml:0:0: Toctree entry in section #0 is not a list",
             "docs/docsite/links.yml:0:0: bla: extra fields not permitted (type=value_error.extra)",
+            "docs/docsite/links.yml:0:0: communication -> forums -> 0 -> url: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> irc_channels -> 0 -> channel: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> mailing_lists -> 0: value is not a valid dict (type=type_error.dict)",
             "docs/docsite/links.yml:0:0: communication -> matrix_rooms: value is not a valid list (type=type_error.list)",
@@ -618,6 +622,7 @@ def test_docsite_linting_failure(tmp_path_factory):
             'docs/docsite/extra-docs.yml:0:0: Section #1 has no "title" entry',
             "docs/docsite/extra-docs.yml:0:0: Toctree entry in section #0 is not a list",
             "docs/docsite/links.yml:0:0: bla: extra fields not permitted (type=value_error.extra)",
+            "docs/docsite/links.yml:0:0: communication -> forums -> 0 -> url: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> irc_channels -> 0 -> channel: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> mailing_lists -> 0: value is not a valid dict (type=type_error.dict)",
             "docs/docsite/links.yml:0:0: communication -> matrix_rooms: value is not a valid list (type=type_error.list)",
@@ -741,6 +746,7 @@ def test_docsite_linting_failure(tmp_path_factory):
             'docs/docsite/extra-docs.yml:0:0: Section #1 has no "title" entry',
             "docs/docsite/extra-docs.yml:0:0: Toctree entry in section #0 is not a list",
             "docs/docsite/links.yml:0:0: bla: extra fields not permitted (type=value_error.extra)",
+            "docs/docsite/links.yml:0:0: communication -> forums -> 0 -> url: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> irc_channels -> 0 -> channel: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> mailing_lists -> 0: value is not a valid dict (type=type_error.dict)",
             "docs/docsite/links.yml:0:0: communication -> matrix_rooms: value is not a valid list (type=type_error.list)",
@@ -862,6 +868,7 @@ def test_docsite_linting_failure(tmp_path_factory):
             'docs/docsite/extra-docs.yml:0:0: Section #1 has no "title" entry',
             "docs/docsite/extra-docs.yml:0:0: Toctree entry in section #0 is not a list",
             "docs/docsite/links.yml:0:0: bla: extra fields not permitted (type=value_error.extra)",
+            "docs/docsite/links.yml:0:0: communication -> forums -> 0 -> url: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> irc_channels -> 0 -> channel: field required (type=value_error.missing)",
             "docs/docsite/links.yml:0:0: communication -> mailing_lists -> 0: value is not a valid dict (type=type_error.dict)",
             "docs/docsite/links.yml:0:0: communication -> matrix_rooms: value is not a valid list (type=type_error.list)",
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		minor_changes:
		- "Allow to mention forums in the Communication section of collection links (https://github.com/ansible-community/antsibull-docs/pull/288)."