Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Collection links: allow to mention forums #288

Merged
merged 1 commit into from
Jul 5, 2024
Merged

Collection links: allow to mention forums #288

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions changelogs/fragments/288-forum.yml
View file
Open in desktop
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)."
6 changes: 5 additions & 1 deletion docs/collection-docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
---
Expand Down Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions src/antsibull_docs/collection_links.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the default link that will show if forums isn't explicitly set?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, this is only for the Communications sections of ansible.builtin (https://docs.ansible.com/ansible/devel/collections/ansible/builtin/#communication). Right now there are no default entries.

}
],
},
}

Expand Down
3 changes: 3 additions & 0 deletions src/antsibull_docs/data/docsite/ansible-docsite/plugins_by_collection.rst.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 %}
Expand Down
3 changes: 3 additions & 0 deletions src/antsibull_docs/data/docsite/simplified-rst/plugins_by_collection.rst.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 %}
Expand Down
11 changes: 10 additions & 1 deletion src/antsibull_docs/schemas/collection_links.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
)


Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-default/collections/ns2/col/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-default/collections/ns2/flatcol/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-no-breadcrumbs/collections/ns2/col/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-no-indexes/collections/ns2/col/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-no-indexes/collections/ns2/flatcol/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-simplified-rst-squash-hierarchy/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-simplified-rst/collections/ns2/col/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-simplified-rst/collections/ns2/flatcol/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-squash-hierarchy/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-use-html-blobs/collections/ns2/col/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__.
Expand Down
2 changes: 2 additions & 0 deletions tests/functional/collections/ansible_collections/ns/col2/docs/docsite/links.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,5 +21,7 @@ communication:
network: true
mailing_lists:
- Ansible Project List
forums:
- topic: foo

bla:
4 changes: 4 additions & 0 deletions tests/functional/collections/ansible_collections/ns2/col/docs/docsite/links.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/
3 changes: 3 additions & 0 deletions tests/functional/collections/ansible_collections/ns2/flatcol/docs/docsite/links.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
7 changes: 7 additions & 0 deletions tests/functional/test_docs_linting.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)",
Expand Down Expand Up @@ -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)",
Expand Down Expand Up @@ -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)",
Expand Down Expand Up @@ -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)",
Expand Down Expand Up @@ -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)",
Expand Down Expand Up @@ -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)",
Expand Down Expand Up @@ -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)",
Expand Down