From 7519b7fa141595460fd7828c88581abe3d5e9d3d Mon Sep 17 00:00:00 2001
From: Sorin Sbarnea <ssbarnea@redhat.com>
Date: Sat, 24 Aug 2024 14:13:13 +0100
Subject: [PATCH] Fix docs jobs (#1884)

---
 constraints.txt |  2 +-
 docs/api.rst    |  4 ++++
 docs/conf.py    |  3 ++-
 jira/client.py  | 10 ++--------
 pyproject.toml  |  2 +-
 tox.ini         |  4 +++-
 6 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/constraints.txt b/constraints.txt
index 9d59e9a7e..db5b572fb 100644
--- a/constraints.txt
+++ b/constraints.txt
@@ -35,7 +35,7 @@ decorator==5.1.1
     # via ipython
 defusedxml==0.7.1
     # via jira (setup.cfg)
-docutils==0.20.1
+docutils==0.21.2
     # via
     #   jira (setup.cfg)
     #   sphinx
diff --git a/docs/api.rst b/docs/api.rst
index a78c0feb1..454190fd5 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -76,6 +76,10 @@ jira.resources module
    :undoc-members:
    :show-inheritance:
 
+.. autoclass:: jira.resources.Field
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 jira.utils module
 -----------------
diff --git a/docs/conf.py b/docs/conf.py
index c04c59b96..df10616e4 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -98,7 +98,8 @@
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-# language = None
+language = "en"
+locale_dirs: list[str] = []
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
diff --git a/jira/client.py b/jira/client.py
index 768097545..871b768b8 100644
--- a/jira/client.py
+++ b/jira/client.py
@@ -2814,14 +2814,8 @@ def add_worklog(
             started (Optional[datetime.datetime]): Moment when the work is logged, if not specified will default to now
             user (Optional[str]): the user ID or name to use for this worklog
             visibility (Optional[Dict[str,Any]]): Details about any restrictions in the visibility of the worklog.
-              Optional when creating or updating a worklog. ::
-                ```js
-                {
-                    "type": "group", # "group" or "role"
-                    "value": "<string>",
-                    "identifier": "<string>" # OPTIONAL
-                }
-                ```
+                Example of visibility options when creating or updating a worklog.
+                ``{ "type": "group", "value": "<string>", "identifier": "<string>"}``
 
         Returns:
             Worklog
diff --git a/pyproject.toml b/pyproject.toml
index 3de8c41dd..2260e162d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -69,7 +69,7 @@ opt = [
 ]
 async = ["requests-futures>=0.9.7"]
 test = [
-    "docutils>=0.12",
+    "docutils>=0.21.2",
     "flaky",
     "MarkupSafe>=0.23",
     "oauthlib",
diff --git a/tox.ini b/tox.ini
index 8df5886e0..8e7441699 100644
--- a/tox.ini
+++ b/tox.ini
@@ -92,7 +92,9 @@ setenv =
     PYTHONHTTPSVERIFY=0
 commands =
     sphinx-build \
-      -a -n -v -W --keep-going \
+      --verbose \
+      --write-all \
+      --nitpicky --fail-on-warning \
       -b html --color \
       -d "{toxworkdir}/docs_doctree" \
       docs/ "{toxworkdir}/docs_out"