docs: fix doc build issues and update antsibull-docs

Author: alperenkose

.github/workflows/ci.yml

@@ -313,7 +313,7 @@ jobs:
         run: poetry add ansible-core^2.16
 
       - name: Add antsibull-docs
-        run: poetry add antsibull-docs^1.11.0
+        run: poetry add antsibull-docs
 
       - name: Install dependencies
         run: poetry install

Makefile

@@ -29,8 +29,10 @@ help:
 
 .PHONY: docs
 docs:		## Build collection documentation
+	rm -rf docs/html
+	rm -rf docs/source/modules
 	mkdir antsibull
-	poetry run antsibull-docs collection --use-current --dest-dir antsibull --no-indexes collections paloaltonetworks.panos
+	poetry run antsibull-docs collection --use-current --dest-dir antsibull --no-indexes paloaltonetworks.panos
 	mkdir -p docs/source/modules
 	mv antsibull/collections/paloaltonetworks/panos/* docs/source/modules
 	rm -rf antsibull

docs/source/conf.py

@@ -4,14 +4,21 @@
 
 extensions = [
     "sphinx_rtd_theme",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx_antsibull_ext"
 ]
 exclude_patterns = []
 
+intersphinx_mapping = {
+     'ansible': ('https://docs.ansible.com/ansible/latest/', None),
+}
+
 html_theme = "sphinx_rtd_theme"
 html_context = {
     "display_github": True,
     "github_user": "PaloAltoNetworks",
     "github_repo": "pan-os-ansible",
-    "github_version": "master",
+    "github_version": "main",
     "conf_py_path": "/docs/source/",
 }

docs/source/index.rst

@@ -50,7 +50,6 @@ Then in your playbooks you can specify that you want to use the
    examples
    modules
    history
-   contributing
    authors
    license
 

plugins/doc_fragments/fragments.py

@@ -323,7 +323,7 @@ class ModuleDocFragment(object):
             - after
         type: str
     existing_rule:
-        description: >
+        description:
             - If I(location=before) or I(location=after), this option specifies
               an existing rule name.  The rule being managed by this module will
               be positioned relative to the value of this parameter.

plugins/modules/panos_dhcp.py

@@ -23,7 +23,7 @@
 ---
 module: panos_dhcp
 short_description: Manage DHCP for an interface.
-description: >
+description:
     - Manage DHCP on PAN-OS firewall.
     - Besides I(state=gathered) to see the the entire DHCP config related to a
       specific interface, you will need to use this module to delete the interface

plugins/modules/panos_dhcp_relay.py

@@ -23,7 +23,7 @@
 ---
 module: panos_dhcp_relay
 short_description: Manage dhcp relay.
-description: >
+description:
     - Manage dhcp relay on PAN-OS firewall.
     - Due to the implementation details of PAN-OS itself, you can use this
       module to create a DHCP config without ever having to use M(paloaltonetworks.panos.panos_dhcp)

plugins/modules/panos_ike_crypto_profile.py

@@ -23,7 +23,7 @@
 ---
 module: panos_ike_crypto_profile
 short_description: Manage IKE Crypto profile on the firewall with subset of settings
-description: >
+description:
     - Use the IKE Crypto Profiles page to specify protocols and algorithms for
       identification, authentication, and encryption (IKEv1 or IKEv2, Phase 1).
 author: "Ivan Bojer (@ivanbojer)"
@@ -98,7 +98,7 @@
             - IKE phase 1 key lifetime in days.
         type: int
     authentication_multiple:
-        description: >
+        description:
             - PAN-OS 7.0 and above.
             - IKEv2 SA reauthentication interval equals I(authentication_multiple)
               times lifetime; 0 means reauthentication is disabled.

plugins/modules/panos_nat_rule2.py

@@ -23,9 +23,9 @@
 ---
 module: panos_nat_rule2
 short_description: Manage a NAT rule
-description: >
+description:
     - Manage a policy NAT rule.
-    - NOTE:  Even though this module supports I(state=merged), due to the
+    - NOTE Even though this module supports I(state=merged), due to the
       complexity of the XML schema for NAT rules, changing a NAT rule's types
       using I(state=merged) will likely result in an error.  Using I(state=merged)
       will work as normal for simple operations, such as adding additional IP addresses

pyproject.toml

@@ -38,7 +38,7 @@ six = "*"
 pycodestyle = "*"
 requests = ">=2.22.0,<3.0"
 toml = "*"
-antsibull-docs = ">=1.11.0,<2.0"
+antsibull-docs = "*"
 
 [tool.poetry.group.ansible-ee]
 optional = true