update doc theme and contributing guide (#1474)

* use furo * run `tox -e deps` * tidy up sphinx config * add sphinx copy-button * update readme and contributing guide * add extension recommendations to match contributing guide instructions * show return type inline in docs https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_use_rtype * add devcontainer badge
pycontribs · Sep 4, 2022 · 354bdf7 · 354bdf7
1 parent 968d983
commit 354bdf7
Show file tree

Hide file tree

Showing 19 changed files with 177 additions and 154 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -20,7 +20,7 @@ repos:
       - id: check-yaml
         files: .*\.(yaml|yml)$
   - repo: https://github.com/codespell-project/codespell.git
-    rev: v2.1.0
+    rev: v2.2.1
     hooks:
       - id: codespell
         name: codespell

diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -0,0 +1,7 @@
+{
+    "recommendations": [
+        "ms-azuretools.vscode-docker",
+        "ms-vscode-remote.remote-containers",
+        "njpwerner.autodocstring"
+    ]
+}
diff --git a/README.rst b/README.rst
@@ -88,53 +88,36 @@ Setup
 =====
 * Fork_ repo
 * Keep it sync_'ed while you are developing
-* Install pyenv_
-* develop and test
-    * Launch docker jira server
-        - ``docker run -dit -p 2990:2990 --name jira addono/jira-software-standalone``
-    * Lint
-        - ``tox -e lint``
-    * Run tests
-        - ``tox``
-    * Run tests for one env only
-        - ``tox -e py38``
-    * Specify what tests to run with pytest_
-        - ``tox -e py39 -- tests/resources/test_attachment.py``
-    * Debug tests with breakpoints by disabling the coverage plugin, with the ``--no-cov`` argument.
-        - Example for VSCode on Windows :
-
-        .. code-block:: java
-
-            {
-                "name": "Pytest",
-                "type": "python",
-                "request": "launch",
-                "python": ".tox\\py39\\Scripts\\python.exe",
-                "module": "pytest",
-                "env": {
-                    "CI_JIRA_URL": "http://localhost:2990/jira",
-                    "CI_JIRA_ADMIN": "admin",
-                    "CI_JIRA_ADMIN_PASSWORD": "admin",
-                    "CI_JIRA_USER": "jira_user",
-                    "CI_JIRA_USER_FULL_NAME": "Newly Created CI User",
-                    "CI_JIRA_USER_PASSWORD": "jira",
-                    "CI_JIRA_ISSUE": "Task",
-                    "PYTEST_TIMEOUT": "0", // Don't timeout
-                },
-                "args": [
-                    // "-v",
-                    "--no-cov", // running coverage affects breakpoints
-                    "tests/resources/test_attachment.py"
-                ]
-            }
-
-    * Build and publish with TWINE
-        - ``tox -e publish``
+
+Automatic (VS Code)
+```````````````````
+.. image:: https://img.shields.io/static/v1?label=Remote%20-%20Containers&message=Open&color=blue&logo=visualstudiocode
+    :target: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/pycontribs/jira
+    :alt: Open in Remote - Containers
+
+Follow the instructions in the `contributing guide`_, which will describe how to use the dev container
+that will automatically setup a suitable environment.
+
+Manual
+``````
+* Install pyenv_ to install a suitable python version.
+* Launch docker jira server
+    - ``docker run -dit -p 2990:2990 --name jira addono/jira-software-standalone``
+
+tox envs
+````````
+* Lint
+    - ``tox -e lint``
+* Run tests
+    - ``tox``
+* Build and publish with TWINE
+    - ``tox -e publish``
 
 .. _Fork: https://help.github.com/articles/fork-a-repo/
 .. _sync: https://help.github.com/articles/syncing-a-fork/
 .. _pyenv: https://amaral.northwestern.edu/resources/guides/pyenv-tutorial
 .. _pytest: https://docs.pytest.org/en/stable/usage.html#specifying-tests-selecting-tests
+.. _contributing guide: https://jira.readthedocs.io/contributing.html
 
 
 Jira REST API Reference Links

diff --git a/constraints.txt b/constraints.txt
@@ -16,70 +16,76 @@ babel==2.10.3
     # via sphinx
 backcall==0.2.0
     # via ipython
+beautifulsoup4==4.11.1
+    # via furo
 certifi==2022.6.15
     # via requests
-cffi==1.15.0
+cffi==1.15.1
     # via cryptography
-charset-normalizer==2.1.0
+charset-normalizer==2.1.1
     # via requests
 colorama==0.4.5
     # via
     #   ipython
     #   pytest
     #   sphinx
-coverage==6.4.1
+coverage==6.4.4
     # via pytest-cov
-cryptography==37.0.2
+cryptography==37.0.4
     # via
     #   pyspnego
     #   requests-kerberos
 decorator==5.1.1
     # via ipython
 defusedxml==0.7.1
     # via jira (setup.cfg)
-docutils==0.17.1
+docutils==0.19
     # via
     #   jira (setup.cfg)
     #   sphinx
-    #   sphinx-rtd-theme
 execnet==1.9.0
     # via
     #   pytest-cache
     #   pytest-xdist
-executing==0.8.3
+executing==0.10.0
     # via stack-data
 filemagic==1.6
     # via jira (setup.cfg)
 flaky==3.7.0
     # via jira (setup.cfg)
+furo==2022.6.21
+    # via jira (setup.cfg)
 idna==3.3
     # via requests
 imagesize==1.4.1
     # via sphinx
 importlib-metadata==4.12.0
-    # via keyring
+    # via
+    #   keyring
+    #   sphinx
 iniconfig==1.1.1
     # via pytest
-ipython==8.2.0
+ipython==8.4.0
     # via jira (setup.cfg)
 jedi==0.18.1
     # via ipython
 jinja2==3.1.2
     # via sphinx
-keyring==23.5.0
+keyring==23.8.2
     # via jira (setup.cfg)
 markupsafe==2.1.1
     # via
     #   jinja2
     #   jira (setup.cfg)
-matplotlib-inline==0.1.3
+matplotlib-inline==0.1.6
     # via ipython
 oauthlib==3.2.0
     # via
     #   jira (setup.cfg)
     #   requests-oauthlib
 packaging==21.3
     # via
+    #   jira (setup.cfg)
     #   pytest
     #   pytest-sugar
     #   sphinx
@@ -104,17 +110,18 @@ pycparser==2.21
     # via cffi
 pygments==2.13.0
     # via
+    #   furo
     #   ipython
     #   sphinx
 pyjwt==2.4.0
     # via
     #   jira (setup.cfg)
     #   requests-jwt
-pyparsing==3.0.7
+pyparsing==3.0.9
     # via packaging
-pyspnego==0.5.4
+pyspnego==0.6.0
     # via requests-kerberos
-pytest==7.1.1
+pytest==7.1.2
     # via
     #   jira (setup.cfg)
     #   pytest-cache
@@ -138,7 +145,7 @@ pytest-timeout==2.1.0
     # via jira (setup.cfg)
 pytest-xdist==2.5.0
     # via jira (setup.cfg)
-pytz==2022.1
+pytz==2022.2.1
     # via babel
 pywin32-ctypes==0.2.0
     # via keyring
@@ -175,11 +182,17 @@ six==1.16.0
     #   requests-mock
 snowballstemmer==2.2.0
     # via sphinx
+soupsieve==2.3.2.post1
+    # via beautifulsoup4
 sphinx==5.1.1
     # via
+    #   furo
     #   jira (setup.cfg)
-    #   sphinx-rtd-theme
-sphinx-rtd-theme==1.0.0
+    #   sphinx-basic-ng
+    #   sphinx-copybutton
+sphinx-basic-ng==0.0.1a12
+    # via furo
+sphinx-copybutton==0.5.0
     # via jira (setup.cfg)
 sphinxcontrib-applehelp==1.0.2
     # via sphinx
@@ -203,13 +216,13 @@ tomli==2.0.1
     # via
     #   coverage
     #   pytest
-traitlets==5.1.1
+traitlets==5.3.0
     # via
     #   ipython
     #   matplotlib-inline
 typing-extensions==4.3.0
     # via jira (setup.cfg)
-urllib3==1.26.11
+urllib3==1.26.12
     # via requests
 wcwidth==0.2.5
     # via prompt-toolkit
@@ -219,8 +232,5 @@ xmlrunner==1.7.7
     # via jira (setup.cfg)
 yanc==0.3.3
     # via jira (setup.cfg)
-zipp==3.8.0
+zipp==3.8.1
     # via importlib-metadata
-
-# The following packages are considered to be unsafe in a requirements file:
-# setuptools
diff --git a/docs/_static/.placeholder b/docs/_static/.placeholder
diff --git a/docs/_static/css/custom_width.css b/docs/_static/css/custom_width.css
diff --git a/docs/_static/python-16.png b/docs/_static/python-16.png
diff --git a/docs/_static/python-256.png b/docs/_static/python-256.png
diff --git a/docs/_static/python-32.png b/docs/_static/python-32.png
diff --git a/docs/_static/python-64.png b/docs/_static/python-64.png
diff --git a/docs/api.rst b/docs/api.rst
@@ -1,10 +1,6 @@
 API Documentation
 *****************
 
-
-.. contents:: Contents
-   :local:
-
 jira package
 ============
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -10,16 +10,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import os
-import sys
-
-import sphinx_rtd_theme
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath(".."))
-from jira import __version__  # noqa
+import jira as py_pkg
 
 # -- General configuration -----------------------------------------------------
 
@@ -33,14 +27,16 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    # External
+    "sphinx_copybutton",
 ]
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.8", None),
     "requests": ("https://requests.readthedocs.io/en/latest/", None),
     "requests-oauthlib": ("https://requests-oauthlib.readthedocs.io/en/latest/", None),
     "ipython": ("https://ipython.readthedocs.io/en/stable/", None),
-    "pip": ("https://pip.readthedocs.io/en/stable/", None),
+    "pip": ("https://pip.pypa.io/en/stable/", None),
 }
 
 autodoc_default_options = {
@@ -75,7 +71,7 @@
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+# templates_path = []
 
 # The suffix of source filenames.
 source_suffix = ".rst"
@@ -87,17 +83,17 @@
 master_doc = "index"
 
 # General information about the project.
-project = "jira-python"
+project = py_pkg.__name__
 copyright = "2012, Atlassian Pty Ltd."
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = __version__
+version = py_pkg.__version__
 # The full version, including alpha/beta/rc tags.
-release = __version__
+release = py_pkg.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -138,16 +134,15 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"
 
 # 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 = {"body_max_width": "100%"}
+# further.  For a list of options available for each theme, see the documentation.
+# https://pradyunsg.me/furo/customisation/
+# html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -168,9 +163,9 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = []
 
-html_style = "css/custom_width.css"
+# html_style = ""
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -270,7 +265,7 @@
 napoleon_google_docstring = True
 napoleon_numpy_docstring = False  # Explicitly prefer Google style docstring
 napoleon_use_param = True  # for type hint support
-
+napoleon_use_rtype = False  # False so the return type is inline with the description.
 
 # -- Options for Texinfo output ------------------------------------------------