Poetry (#216)

* add nox + poetry files

* update ci.yml

* drop python 3.5 support from CI matrix

* install poetry

* commit poetry lock file

* add sphinx version to CI matrix

* remove quotes

* add missing dollar sign

* change version specifications to strings

* try to set names for the matrix jobs

* remove deprecated files

* treat poetry.lock as a binary

* add more documentation, deprecate setup file

* try to convince github to ignore the poetry.lock file in diffs

* try to convince github to ignore the poetry.lock file in diffs

* try to convince github to ignore the poetry.lock file in diffs

* try to convince github to ignore the poetry.lock file in diffs

* tidy up

* tidy noxfile

* update lock file

* bump dependencies

* prune over-enthusiastic use of the word 'also'

also change a <ul> to an <ol>

* add py39 to test matrix

* move logic from noxfile to Makefile

* add flake8

* fix outstanding lint errors

* add CI target

* re-add 'test_doc_github_61'

* add linting for pep8 naming compliance

* add trailing newline to file

* fix lint error

* add makefile targets for building docs

* move 'contributing' guide from markdown file to docs/ directory

* add missing newline

* fix flake8 lints

.flake8

@@ -0,0 +1,4 @@
+[flake8]
+max-line-length = 120
+per-file-ignores =
+    tests/data/service_github.py: E501

.gitattributes

@@ -0,0 +1,2 @@
+poetry.lock linguist-generated=true
+poetry.lock -diff

.github/workflows/ci.yaml

@@ -0,0 +1,40 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  tests:
+    name: "Test (python: ${{ matrix.python-version }}, sphinx: ${{ matrix.sphinx-version }})"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-20.04]
+        python-version: ["3.6", "3.7", "3.8", "3.9"]
+        sphinx-version: ["2.2", "2.3", "2.4", "3.0", "3.2"]
+        exclude:
+          - python-version: "3.6"
+            sphinx-version: "3.2"
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set Up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install Nox Dependencies
+        run: |
+          python -m pip install poetry nox nox-poetry
+      - name: Run Tests
+        run: nox --non-interactive --session "tests-${{ matrix.python-version }}(sphinx='${{ matrix.sphinx-version }}')" -- --full-trace
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set Up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.9"
+      - name: Install Nox Dependencies
+        run: |
+          python -m pip install poetry nox nox-poetry
+      - name: Run Lint
+        run: nox --non-interactive --session lint -- --full-trace

.gitignore

@@ -16,5 +16,5 @@ _build
 .doctrees
 docs/github_images/
 .eggs/
-
 docs/_images/need_pie_*.png
+poetry.lock

Makefile

@@ -0,0 +1,21 @@
+SRC_FILES = sphinxcontrib/ tests/ noxfile.py
+
+.PHONY: lint
+lint:
+	poetry run flake8 ${SRC_FILES}
+
+.PHONY: test
+test:
+	poetry run nosetests -w tests
+
+.PHONY: test-matrix
+test-matrix:
+	nox
+
+.PHONY: docs-html
+docs-html:
+	poetry run make --directory docs/ html
+
+.PHONY: docs-pdf
+docs-pdf:
+	poetry run make --directory docs/ latexpdf

docs/contributing.rst

@@ -0,0 +1,77 @@
+Contributing
+============
+
+The following provides a guide for developers wishing to contribute
+to Sphinx-Needs
+
+Installing Dependencies
+-----------------------
+
+Sphinxcontrib-Needs requires only
+`Poetry <https://python-poetry.org/>`__ to be installed as a system
+dependency, the rest of the dependencies are ‘bootstrapped’ and
+installed in an isolated environment by Poetry.
+
+1. `Install Poetry <https://python-poetry.org/docs/#installation>`__
+
+2. Install project dependencies
+
+   ::
+
+       poetry install
+
+Running Tests
+-------------
+
+::
+
+   make test
+
+Linting
+-------
+
+::
+
+   make lint
+
+Running Test Matrix
+-------------------
+
+This project provides a test matrix for running the tests across a range
+of python and sphinx versions. This is used primarily for continuous
+integration.
+
+`Nox <https://nox.thea.codes/en/stable/>`__ is used as a test runner.
+
+Running the matrix tests requires additional system-wide dependencies
+
+1. `Install
+   Nox <https://nox.thea.codes/en/stable/tutorial.html#installation>`__
+2. `Install Nox-Poetry <https://pypi.org/project/nox-poetry/>`__
+3. You will also need multiple Python versions available. You can manage
+   these using `Pyenv <https://github.com/pyenv/pyenv>`__
+
+you can run the test matrix by using the ``nox`` command
+
+::
+
+   nox
+
+or using the provided Makefile
+
+::
+
+   make test-matrix
+
+for a full list of available options, refer to the Nox documentation,
+and the local `noxfile <.../noxfile.py>`__
+
+Running Commands
+----------------
+
+See the Poetry documentation for a list of commands.
+
+See the local `Makefile <../Makefile>`__ for a full list of commands
+
+In order to run custom commands inside the isolated environment, they
+should be prefixed with “poetry run” (ie. ``poetry run <command>``).

docs/index.rst

@@ -307,6 +307,7 @@ Content
    snippets
    support
    changelog
+   contributing
    license
    contributors
 

noxfile.py

@@ -0,0 +1,44 @@
+import nox
+from nox_poetry import session
+
+
+PYTHON_VERSIONS = ["3.6", "3.7", "3.8", "3.9"]
+SPHINX_VERSIONS = ["2.2", "2.3", "2.4", "3.0", "3.2"]
+TEST_DEPENDENCIES = [
+    "nose",
+    "sphinx_testing",
+    "sphinxcontrib.plantuml",
+    "matplotlib",
+    "responses",
+    "sphinx_copybutton",
+]
+LINT_DEPENDENCIES = [
+    "flake8",
+    "pep8-naming",
+]
+
+
+def is_supported(python: str, sphinx: str) -> bool:
+    return not (python == "3.6" and float(sphinx) > 3.0)
+
+
+def run_tests(session, sphinx):
+    session.install(".")
+    session.install(*TEST_DEPENDENCIES)
+    session.run("pip", "install", f"sphinx=={sphinx}", silent=True)
+    session.run("make", "test", external=True)
+
+
+@session(python=PYTHON_VERSIONS)
+@nox.parametrize("sphinx", SPHINX_VERSIONS)
+def tests(session, sphinx):
+    if is_supported(session.python, sphinx):
+        run_tests(session, sphinx)
+    else:
+        session.skip("unsupported combination")
+
+
+@session(python="3.9")
+def lint(session):
+    session.install(*LINT_DEPENDENCIES)
+    session.run("make", "lint", external=True)