Fix sphinx warnings (pyinfra-dev#1181)

* Docs: Fix references * Fix reference by setting myst_heading_anchors Refer to executablebooks/MyST-Parser#519 (comment) for more details * Fix sphinx warnings * Fix warning re: document not being part of toctree * Fix "Unexpected section title or transition" warning * Fix "Explicit markup ends without a blank line; unexpected unindent" warning * Fix "Unexpected indentation" error * Fix "undefined label" warning * Fix regular expression for "**extra_props" * Fix "Non-consecutive header level increase" warning * Fix formatting --------- Co-authored-by: simonhammes <[email protected]>
Pirols · Sep 1, 2024 · 983426a · 983426a
1 parent aad6c3b
commit 983426a
Show file tree

Hide file tree

Showing 15 changed files with 37 additions and 25 deletions.
diff --git a/docs/api/deploys.md b/docs/api/deploys.md
@@ -34,7 +34,7 @@ install_mariadb()
 
 ## Global Arguments
 
-Deploys accept the same [global arguments as as operations](../deploys.html#global-arguments) and they apply to every operation call within that deploy. Taking the above example:
+Deploys accept the same [global arguments as operations](../arguments) and they apply to every operation call within that deploy. Taking the above example:
 
 
 ```py

diff --git a/docs/cli.md b/docs/cli.md
@@ -46,7 +46,7 @@ By default pyinfra only prints high level information (this host connected, this
 
 ## Inventory
 
-When using pyinfra inventory can be provided directly via the command line or [defined in a file](./deploys.html#inventory). Both support the full range of [connectors](./connectors) and multiple hosts. Some CLI examples:
+When using pyinfra inventory can be provided directly via the command line or [defined in a file](./inventory-data). Both support the full range of [connectors](./connectors) and multiple hosts. Some CLI examples:
 
 ```sh
 # Load inventory hosts from a file

diff --git a/docs/compatibility.md b/docs/compatibility.md
@@ -39,8 +39,8 @@ pyinfra aims to be compatible with all Unix-like operating systems and is curren
     * HardenedBSD 11
     * DragonflyBSD 5
 + OpenSUSE (leap15 + tumbleweed)
-+ macOS 10.15 (with [`@local` connector](connectors.html#local))
-+ Docker (with [`@docker` connector](connectors.html#docker))
++ macOS 10.15 (with [`@local` connector](./connectors/local))
++ Docker (with [`@docker` connector](./connectors/docker))
 
 In general, the only requirement on the remote side is shell access. POSIX commands are used where possible for facts and operations, so most of the ``server`` and ``files`` operations should work anywhere POSIX.
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -46,6 +46,8 @@
     "primary_doc_version": "3.x",
 }
 
+myst_heading_anchors = 3
+
 templates_path = ["templates"]
 
 html_favicon = "static/logo_small.png"

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -7,7 +7,7 @@ Third party pull requests help expand pyinfra's functionality and are essential
 ## Guides
 
 + [How to write operations](api/operations)
-+ [How to write facts](api/facts)
++ [How to write facts](api/operations.md#facts)
 + [How to write connectors](api/connectors)
 + [API reference](api/reference)
 

diff --git a/docs/install.md b/docs/install.md
@@ -1,3 +1,8 @@
+---
+# Ignore warning about this page not being included in any toctree
+orphan: true
+---
+
 # Installation
 
 ## Pip

diff --git a/docs/support.md b/docs/support.md
@@ -5,16 +5,16 @@ Need a hand with using pyinfra or have some questions? You can find official pyi
 + Chat in [the `pyinfra` Matrix room](https://matrix.to/#/#pyinfra:matrix.org)
 + Ask questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/pyinfra) (be sure to use the `pyinfra` tag!)
 
-### I think I've got a bug!
+## I think I've got a bug!
 
 + Please have a quick scan of the [the compatibility page](./compatibility) to see if the issue is referenced there
 + Check [the issue list](https://github.com/Fizzadar/pyinfra/issues) to see if anyone else has this issue
 + Submit [a new bug report](https://github.com/Fizzadar/pyinfra/issues/new/choose)
 
-### I have an idea!
+## I have an idea!
 
 Please consider [submitting a feature request](https://github.com/Fizzadar/pyinfra/issues/new/choose).
 
-### I'd like to contribute!
+## I'd like to contribute!
 
 Fantastic! Please see [the contributing docs](./contributing).
diff --git a/docs/utils.py b/docs/utils.py
@@ -7,7 +7,7 @@ def title_line(char, string):
 
 def format_doc_line(line):
     # Bold the <arg>: part of each line
-    line = re.sub(r"\+ ([0-9a-z_\/]+)(.*)", r"+ **\1**\2", line)
+    line = re.sub(r"\+ ([0-9a-z_\/\*]+)(.*)", r"+ **\1**\2", line)
 
     # Strip the first 4 characters (first indent from docstring)
     return line[4:]
diff --git a/pyinfra/api/arguments.py b/pyinfra/api/arguments.py
@@ -137,7 +137,7 @@ def generate_env(config: "Config", value: dict) -> dict:
     ),
     "_chdir": ArgumentMeta(
         "Directory to switch to before executing the command.",
-        default=lambda _: "",
+        default=lambda _: None,
     ),
     "_env": ArgumentMeta(
         "Dictionary of environment variables to set.",

diff --git a/pyinfra/facts/hardware.py b/pyinfra/facts/hardware.py
@@ -109,6 +109,7 @@ class NetworkDevices(FactBase):
     ``ipv6_addresses`` facts for easier-to-use shortcuts to get device addresses.
 
     .. code:: python
+
         "enp1s0": {
             "ether": "12:34:56:78:9A:BC",
             "mtu": 1500,

diff --git a/pyinfra/facts/selinux.py b/pyinfra/facts/selinux.py
@@ -58,7 +58,8 @@ def process(self, output):
 class FileContextMapping(FactBase):
     """
     Returns structured SELinux file context data for the specified target path prefix
-    using the same format as :ref:`selinux.FileContext`.  If there is no mapping, it returns ``{}``
+    using the same format as :ref:`facts:selinux.FileContext`.
+    If there is no mapping, it returns ``{}``
     Note: This fact requires root privileges.
     """
 
@@ -85,6 +86,7 @@ class SEPorts(FactBase):
     Note: This fact requires root privileges.
 
     .. code:: python
+
         {
             "tcp": { 22: "ssh_port_t", ...},
             "udp": { ...}

diff --git a/pyinfra/operations/apt.py b/pyinfra/operations/apt.py
@@ -53,7 +53,8 @@ def key(src: str | None = None, keyserver: str | None = None, keyid: str | list[
     .. warning::
         ``apt-key`` is deprecated in Debian, it is recommended NOT to use this
         operation and instead follow the instructions here:
-            https://wiki.debian.org/DebianRepository/UseThirdParty
+
+        https://wiki.debian.org/DebianRepository/UseThirdParty
 
     **Examples:**
 

diff --git a/pyinfra/operations/files.py b/pyinfra/operations/files.py
@@ -256,7 +256,7 @@ def line(
         change bits of lines, see ``files.replace``.
 
     Regex line escaping:
-        If matching special characters (eg a crontab line containing *), remember to escape
+        If matching special characters (eg a crontab line containing ``*``), remember to escape
         it first using Python's ``re.escape``.
 
     Backup:
@@ -523,7 +523,7 @@ def sync(
     + mode: permissions of the files
     + dir_mode: permissions of the directories
     + delete: delete remote files not present locally
-    + exclude: string or list/tuple of strings to match & exclude files (eg *.pyc)
+    + exclude: string or list/tuple of strings to match & exclude files (eg ``*.pyc``)
     + exclude_dir: string or list/tuple of strings to match & exclude directories (eg node_modules)
     + add_deploy_dir: interpret src as relative to deploy directory instead of current directory
 

diff --git a/pyinfra/operations/zfs.py b/pyinfra/operations/zfs.py
@@ -33,14 +33,14 @@ def dataset(
 
     .. code:: python
 
-    zfs.dataset(
-        "tank/srv",
-        mountpoint="/srv",
-        compression="lz4",
-        properties={"com.sun:auto_snapshot": "true"}
-    )
-    zfs.dataset("tank/vm-disks/db_srv_04", volume_size="32G") # creates a volume
-    zfs.dataset("tank/home@old_version", present=False)
+        zfs.dataset(
+            "tank/srv",
+            mountpoint="/srv",
+            compression="lz4",
+            properties={"com.sun:auto_snapshot": "true"}
+        )
+        zfs.dataset("tank/vm-disks/db_srv_04", volume_size="32G") # creates a volume
+        zfs.dataset("tank/home@old_version", present=False)
 
     """
 
@@ -99,7 +99,7 @@ def snapshot(snapshot_name, present=True, recursive=False, properties={}, **extr
 
     .. code:: python
 
-    zfs.snapshot("tank/home@weekly_backup")
+        zfs.snapshot("tank/home@weekly_backup")
 
     """
     properties.update(extra_props)
@@ -134,7 +134,7 @@ def volume(
 
     .. code:: python
 
-    zfs.volume("tank/vm-disks/db_srv_04", "32G")
+        zfs.volume("tank/vm-disks/db_srv_04", "32G")
 
     """
     properties.update(extra_props)
@@ -163,7 +163,7 @@ def filesystem(fs_name, present=True, recursive=False, properties={}, **extra_pr
 
     .. code:: python
 
-    zfs.filesystem("tank/vm-disks/db_srv_04", "32G")
+        zfs.filesystem("tank/vm-disks/db_srv_04", "32G")
 
     """
     properties.update(extra_props)

diff --git a/scripts/generate_connectors_docs.py b/scripts/generate_connectors_docs.py
@@ -36,6 +36,7 @@ def build_connectors_docs():
             lines.append(title_line("~", "Examples"))
             lines.append("")
             lines.append(cleandoc(examples_doc))
+            lines.append("")
         else:
             data_title = "Usage"
             lines.append(data_title)
-Original file line number
+Diff line change
@@ Expand Up / @@ -34,7 +34,7 @@ install_mariadb() @@
     ## Global Arguments
-    Deploys accept the same [global arguments as as operations](../deploys.html#global-arguments) and they apply to every operation call within that deploy. Taking the above example:
+    Deploys accept the same [global arguments as operations](../arguments) and they apply to every operation call within that deploy. Taking the above example:
     ```py
@@ Expand Down @@