Fix docstring generation of jira client and minor doc layouting fix (p…

…ycontribs#1038) * some part of the documentation wasn't properly generated. see pycontribs#1035 * adding warnings about deprecated auth mechanism for jira cloud in examples * this should fix the mismatch between the white background and the line length of the docs Co-authored-by: Neefs, Jef <[email protected]>
BroadbandForum · May 15, 2021 · 16c1053 · 16c1053
1 parent e9e0d60
commit 16c1053
Show file tree

Hide file tree

Showing 4 changed files with 27 additions and 3 deletions.
diff --git a/docs/_static/css/custom_width.css b/docs/_static/css/custom_width.css
@@ -0,0 +1,5 @@
+@import url("theme.css");
+/* as found in https://stackoverflow.com/a/62338678/2559785 */
+.wy-nav-content {
+    max-width: 90%; !important
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -167,7 +167,7 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {"body_max_width": "100%"}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -194,6 +194,8 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+html_style = "css/custom_width.css"
+
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 html_last_updated_fmt = "%b %d, %Y"

diff --git a/docs/examples.rst b/docs/examples.rst
@@ -54,18 +54,35 @@ Pass a tuple of (username, password) to the ``auth`` constructor argument::
 Using this method, authentication happens during the initialization of the object. If the authentication is successful,
 the retrieved session cookie will be used in future requests. Upon cookie expiration, authentication will happen again transparently.
 
+.. warning::
+    This way of authentication is not supported anymore on Jira Cloud. You can find the deprecation notice `here <https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-basic-auth-and-cookie-based-auth>`_.
+
+    For Jira Cloud use the basic_auth= :ref:`basic-auth-api-token` authentication
+
 HTTP BASIC
 ^^^^^^^^^^
 
+(username, password)
+""""""""""""""""""""
+
 Pass a tuple of (username, password) to the ``basic_auth`` constructor argument::
 
     auth_jira = JIRA(basic_auth=('username', 'password'))
 
+.. warning::
+    This way of authentication is not supported anymore on Jira Cloud. You can find the deprecation notice `here <https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-basic-auth-and-cookie-based-auth>`_
+
+    For Jira Cloud use the basic_auth= :ref:`basic-auth-api-token` authentication
+
+.. _basic-auth-api-token:
+
+(username, api_token)
+"""""""""""""""""""""
+
 Or pass a tuple of (email, api_token) to the ``basic_auth`` constructor argument (JIRA cloud)::
 
     auth_jira = JIRA(basic_auth=('email', 'API token'))
 
-
 OAuth
 ^^^^^
 

diff --git a/jira/client.py b/jira/client.py
@@ -413,8 +413,8 @@ def __init__(
         :param async_workers: Set the number of worker threads for async operations.
         :type async_workers: int
         :param timeout: Set a read/connect timeout for the underlying calls to Jira (default: None)
+            Obviously this means that you cannot rely on the return code when this is enabled.
         :type timeout: Optional[Any]
-        Obviously this means that you cannot rely on the return code when this is enabled.
         :param max_retries: Sets the amount Retries for the HTTP sessions initiated by the client. (Default: 3)
         :type max_retries: int
         :param proxies: Sets the proxies for the HTTP session.