From 354bdf777d9fc76bc790de2e640e83818ef25a14 Mon Sep 17 00:00:00 2001 From: Adel Haddad <26027314+adehad@users.noreply.github.com> Date: Sun, 4 Sep 2022 11:21:07 +0100 Subject: [PATCH] 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 --- .pre-commit-config.yaml | 2 +- .vscode/extensions.json | 7 ++ README.rst | 67 +++++++------------ constraints.txt | 56 +++++++++------- docs/_static/.placeholder | 0 docs/_static/css/custom_width.css | 5 -- docs/_static/python-16.png | Bin 1404 -> 0 bytes docs/_static/python-256.png | Bin 11455 -> 0 bytes docs/_static/python-32.png | Bin 1374 -> 0 bytes docs/_static/python-64.png | Bin 2596 -> 0 bytes docs/api.rst | 4 -- docs/conf.py | 35 +++++----- docs/contributing.rst | 107 ++++++++++++++++++++---------- docs/examples.rst | 3 - docs/index.rst | 6 -- docs/installation.rst | 14 ++-- docs/jirashell.rst | 19 ++++-- docs/templates/.placeholder | 0 setup.cfg | 6 +- 19 files changed, 177 insertions(+), 154 deletions(-) create mode 100644 .vscode/extensions.json delete mode 100644 docs/_static/.placeholder delete mode 100644 docs/_static/css/custom_width.css delete mode 100644 docs/_static/python-16.png delete mode 100644 docs/_static/python-256.png delete mode 100644 docs/_static/python-32.png delete mode 100644 docs/_static/python-64.png delete mode 100644 docs/templates/.placeholder diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1e8de91c7..25f102154 100644 --- 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 new file mode 100644 index 000000000..9466a596b --- /dev/null +++ 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 index b3ea8671b..0aa704854 100644 --- 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 index 3201ff956..63a83657a 100644 --- a/constraints.txt +++ b/constraints.txt @@ -16,20 +16,22 @@ 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 @@ -37,42 +39,45 @@ 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 @@ -80,6 +85,7 @@ oauthlib==3.2.0 # 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 deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/_static/css/custom_width.css b/docs/_static/css/custom_width.css deleted file mode 100644 index f9c89c8d2..000000000 --- a/docs/_static/css/custom_width.css +++ /dev/null @@ -1,5 +0,0 @@ -@import url("theme.css"); -/* as found in https://stackoverflow.com/a/62338678/2559785 */ -.wy-nav-content { - max-width: 90%; !important -} diff --git a/docs/_static/python-16.png b/docs/_static/python-16.png deleted file mode 100644 index d1c07f0a8768f7f8a6c09c3724d8940de58adc9f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1404 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 z%0A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 z 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 v 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 ------------------------------------------------ diff --git a/docs/contributing.rst b/docs/contributing.rst index 7acdb7592..0f8c39c23 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -37,60 +37,95 @@ Contributing Code Testing ******* -To test code run:: +Dev Container ++++++++++++++ - make test-all +We utilise Docker in order to generate a test Jira Server instance. -This will run the code in a virtual environment, and will test across the -versions of python which are installed. It will also install tox if it is -not already installed. +This can be run manually, or automated using VS Code Dev Containers: -Alternatively if you do not have make you can always run:: +#. Open the folder of the repository with VS Code +#. Ensure you have Docker running +#. Ensure you have the ``ms-azuretools.vscode-docker`` and ``ms-vscode-remote.remote-containers`` + extensions installed. +#. You should be able to do ``View >> Command Palette`` (or equivalent) and search for: + ``Remote-containers: Rebuild and Reopen in container``. - pip install tox +This will use the ``.devcontainer\Dockerfile`` as a base image with configurations +dictated by ``.devcontainer\devcontainer.json``. + +.. TIP:: + The Docker extension can be used to monitor the progress of the Jira server build, + it takes a while! The tests will only run once the server is up and reachable on: http://localhost:2990/jira + + +Running Tests ++++++++++++++ + +Using tox + +.. code-block:: bash + + python -m pip install pipx + pipx install tox tox +* 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`` + - ``tox -e py38 -- -m allow_on_cloud`` (Run only the cloud tests) +* 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" + ] + } + +.. _pytest: https://docs.pytest.org/en/stable/usage.html#specifying-tests-selecting-tests + + Issues and Feature Requests *************************** * Check to see if there's an existing issue/pull request for the bug/feature. All issues are at https://github.com/pycontribs/jira/issues and pull requests are at https://github.com/pycontribs/jira/pulls. -* If there isn't an existing issue there, please file an issue. The ideal - report includes: +* If there isn't an existing issue there, please file an issue. - * A description of the problem/suggestion. - * How to recreate the bug. - * If relevant, including the versions of your: + * An example template is provided for: - * Python interpreter (3.8, etc) - * jira-python - * Operating System and Version (Windows 7, OS X 10.10, Ubuntu 14.04, etc.) - * IPython if using jirashell - * Optionally of the other dependencies involved + * Bugs: https://github.com/pycontribs/jira/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml + * Features: https://github.com/pycontribs/jira/blob/main/.github/ISSUE_TEMPLATE/feature_request.yml * If possible, create a pull request with a (failing) test case demonstrating what's wrong. This makes the process for fixing bugs quicker & gets issues resolved sooner. - * Here is an template - :: - - Description: - - Python Interpreter: - jira-python: - OS: - IPython (Optional): - Other Dependencies: - - Steps To Reproduce: - 1. - 2. - 3. - ... - - Stack Trace: - Issues diff --git a/docs/examples.rst b/docs/examples.rst index 69277343b..2900fb3d0 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -1,9 +1,6 @@ Examples ******** -.. contents:: Contents - :local: - Here's a quick usage example: .. literalinclude:: ../examples/basic_use.py diff --git a/docs/index.rst b/docs/index.rst index 8c28f4d1f..49c77424d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,9 +1,3 @@ -.. jira-python documentation main file, created by - sphinx-quickstart on Thu May 3 17:01:50 2012. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - - Python Jira ########### Python library to work with Jira APIs diff --git a/docs/installation.rst b/docs/installation.rst index 47e1761f6..acb573fbd 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,20 +1,19 @@ Installation ************ -.. contents:: Contents - :local: - The easiest (and best) way to install jira-python is through `pip `_:: - $ pip install jira + pip install jira This will handle installation of the client itself as well as the requirements. If you're going to run the client standalone, we strongly recommend using a `virtualenv `_, -which pip can also set up for you:: +which pip can also set up for you + +.. code-block:: bash - $ pip -E jira_python install jira - $ workon jira_python + pip -E jira_python install jira + workon jira_python Doing this creates a private Python "installation" that you can freely upgrade, degrade or break without putting the critical components of your system at risk. @@ -23,7 +22,6 @@ Source packages are also available at PyPI: https://pypi.python.org/pypi/jira/ -.. _Dependencies: Dependencies ============ diff --git a/docs/jirashell.rst b/docs/jirashell.rst index de84fe21f..63f3a4482 100644 --- a/docs/jirashell.rst +++ b/docs/jirashell.rst @@ -5,9 +5,15 @@ There is no substitute for play. The only way to really know a service, API or p it, and bang your elbows -- trial and error. A REST design is especially well-suited for active exploration, and the ``jirashell`` script (installed automatically when you use pip) is designed to help you do exactly that. -Run it from the command line:: +.. code-block:: bash - $ jirashell -s https://jira.atlassian.com + pip install jira[cli] + +Run it from the command line + +.. code-block:: bash + + jirashell -s https://jira.atlassian.com *** Jira shell active; client is in 'jira'. Press Ctrl-D to exit. @@ -18,12 +24,17 @@ This is a specialized Python interpreter (built on IPython) that lets you explor Python code is acceptable input. The shell builds a ``JIRA`` client object for you (based on the launch parameters) and stores it in the ``jira`` object. -Try getting an issue:: +Try getting an issue + +.. code-block:: python In [1]: issue = jira.issue('JRA-1330') ``issue`` now contains a reference to an issue ``Resource``. To see the available properties and methods, hit the TAB -key:: +key + + +.. code-block:: python In [2]: issue. issue.delete issue.fields issue.id issue.raw issue.update diff --git a/docs/templates/.placeholder b/docs/templates/.placeholder deleted file mode 100644 index e69de29bb..000000000 diff --git a/setup.cfg b/setup.cfg index 6ac9f3a6b..fd6708fda 100644 --- a/setup.cfg +++ b/setup.cfg @@ -65,8 +65,10 @@ cli = ipython>=4.0.0 keyring docs = - Sphinx>=2.2.0 - sphinx_rtd_theme>=0.4.3 + sphinx>=5.0.0 + sphinx-copybutton + # HTML Theme + furo opt = filemagic>=1.6 PyJWT