From 6ae1bc6144aa43a6adcea7923127940767dc72a5 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 29 Jun 2024 21:44:56 +0200 Subject: [PATCH] Allow to mention forums. --- changelogs/fragments/288-forum.yml | 2 ++ docs/collection-docs.md | 6 +++++- src/antsibull_docs/collection_links.py | 6 ++++++ .../ansible-docsite/plugins_by_collection.rst.j2 | 3 +++ .../simplified-rst/plugins_by_collection.rst.j2 | 3 +++ src/antsibull_docs/schemas/collection_links.py | 11 ++++++++++- .../baseline-default/collections/ns2/col/index.rst | 1 + .../collections/ns2/flatcol/index.rst | 1 + .../collections/ns2/col/index.rst | 1 + .../collections/ns2/flatcol/index.rst | 1 + .../baseline-no-indexes/collections/ns2/col/index.rst | 1 + .../collections/ns2/flatcol/index.rst | 1 + .../index.rst | 1 + .../collections/ns2/col/index.rst | 1 + .../collections/ns2/flatcol/index.rst | 1 + tests/functional/baseline-squash-hierarchy/index.rst | 1 + .../collections/ns2/col/index.rst | 1 + .../ns/col2/docs/docsite/links.yml | 2 ++ .../ns2/col/docs/docsite/links.yml | 4 ++++ .../ns2/flatcol/docs/docsite/links.yml | 3 +++ tests/functional/test_docs_linting.py | 7 +++++++ 21 files changed, 56 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/288-forum.yml diff --git a/changelogs/fragments/288-forum.yml b/changelogs/fragments/288-forum.yml new file mode 100644 index 00000000..468ac165 --- /dev/null +++ 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 index 6ac12654..21e2f861 100644 --- 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 index b8ba86e5..a4bbe89a 100644 --- 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 index da52aec3..c5ad6dd5 100644 --- 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 }@ `__. {% 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 index 148914d6..07441e37 100644 --- 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 }@ `__. {% endfor %} diff --git a/src/antsibull_docs/schemas/collection_links.py b/src/antsibull_docs/schemas/collection_links.py index 72a0b2ed..acd46848 100644 --- 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 index ec8d9d62..7fdf57f6 100644 --- 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 `__. - Matrix room :literal:`#users:ansible.im`: `General usage and support questions `__. - IRC channel :literal:`#ansible` (Libera network): `General usage and support questions `__. diff --git a/tests/functional/baseline-default/collections/ns2/flatcol/index.rst b/tests/functional/baseline-default/collections/ns2/flatcol/index.rst index e799aab5..3b9930e9 100644 --- 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 `__. - Matrix room :literal:`#users:ansible.im`: `General usage and support questions `__. - IRC channel :literal:`#ansible` (Libera network): `General usage and support questions `__. diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/index.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/index.rst index 6d7cb94c..a622b077 100644 --- 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 `__. - Matrix room :literal:`#users:ansible.im`: `General usage and support questions `__. - IRC channel :literal:`#ansible` (Libera network): `General usage and support questions `__. diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/index.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/index.rst index 09e9338b..fb1b2fb5 100644 --- 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 `__. - Matrix room :literal:`#users:ansible.im`: `General usage and support questions `__. - IRC channel :literal:`#ansible` (Libera network): `General usage and support questions `__. diff --git a/tests/functional/baseline-no-indexes/collections/ns2/col/index.rst b/tests/functional/baseline-no-indexes/collections/ns2/col/index.rst index ec8d9d62..7fdf57f6 100644 --- 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 `__. - Matrix room :literal:`#users:ansible.im`: `General usage and support questions `__. - IRC channel :literal:`#ansible` (Libera network): `General usage and support questions `__. diff --git a/tests/functional/baseline-no-indexes/collections/ns2/flatcol/index.rst b/tests/functional/baseline-no-indexes/collections/ns2/flatcol/index.rst index e799aab5..3b9930e9 100644 --- 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 `__. - Matrix room :literal:`#users:ansible.im`: `General usage and support questions `__. - IRC channel :literal:`#ansible` (Libera network): `General usage and support questions `__. diff --git a/tests/functional/baseline-simplified-rst-squash-hierarchy/index.rst b/tests/functional/baseline-simplified-rst-squash-hierarchy/index.rst index 7d2962ab..101bf064 100644 --- 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 `__. - Matrix room :literal:`#users:ansible.im`: `General usage and support questions `__. - IRC channel :literal:`#ansible` (Libera network): `General usage and support questions `__. diff --git a/tests/functional/baseline-simplified-rst/collections/ns2/col/index.rst b/tests/functional/baseline-simplified-rst/collections/ns2/col/index.rst index 7d2962ab..101bf064 100644 --- 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 `__. - Matrix room :literal:`#users:ansible.im`: `General usage and support questions `__. - IRC channel :literal:`#ansible` (Libera network): `General usage and support questions `__. diff --git a/tests/functional/baseline-simplified-rst/collections/ns2/flatcol/index.rst b/tests/functional/baseline-simplified-rst/collections/ns2/flatcol/index.rst index edc563dd..c8a7e852 100644 --- 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 `__. - Matrix room :literal:`#users:ansible.im`: `General usage and support questions `__. - IRC channel :literal:`#ansible` (Libera network): `General usage and support questions `__. diff --git a/tests/functional/baseline-squash-hierarchy/index.rst b/tests/functional/baseline-squash-hierarchy/index.rst index 7e57c1a0..153c553c 100644 --- 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 `__. - Matrix room :literal:`#users:ansible.im`: `General usage and support questions `__. - IRC channel :literal:`#ansible` (Libera network): `General usage and support questions `__. 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 index ec8d9d62..7fdf57f6 100644 --- 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 `__. - Matrix room :literal:`#users:ansible.im`: `General usage and support questions `__. - IRC channel :literal:`#ansible` (Libera network): `General usage and support questions `__. 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 index f4c2266c..8c2a4cef 100644 --- 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 index 405836e4..0b1a34d9 100644 --- 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 index 305af965..cc0c6f8f 100644 --- 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 index 31eb784a..ce68b035 100644 --- 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)",