[#2] fix string and symlink handling, adding first basic tests

Author: kreuzberger

.gitignore

@@ -69,7 +69,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+_build/
 
 # PyBuilder
 target/
@@ -131,4 +131,4 @@ dmypy.json
 .envrc
 .idea
 
-_collections/
+_collections/

Makefile

@@ -0,0 +1,43 @@
+SRC_FILES = sphinxcontrib/ tests/ noxfile.py
+
+.PHONY: list
+list:
+	@$(MAKE) -pRrq -f $(lastword $(MAKEFILE_LIST)) : 2>/dev/null | awk -v RS= -F: '/^# File/,/^# Finished Make data base/ {if ($$1 !~ "^[#.]") {print $$1}}' | sort | egrep -v -e '^[^[:alnum:]]' -e '^$@$$'
+
+.PHONY: lint
+lint:
+	pre-commit run --all-files
+
+.PHONY: test
+test:
+	poetry run pytest -n auto --tb=long tests/
+
+.PHONY: test
+test-short:
+	poetry run pytest -n auto --tb=long --ignore-glob="*official*" tests/
+
+.PHONY: test-matrix
+test-matrix:
+	nox
+
+.PHONY: docs-html
+docs-html:
+	poetry run sphinx-build -a -E -j auto -b html docs/ docs/_build
+
+.PHONY: docs-html
+docs-html-fast:
+	poetry run sphinx-build -j auto -b html docs/ docs/_build
+
+.PHONY: docs-pdf
+docs-pdf:
+	poetry run make --directory docs/ clean && make --directory docs/ latexpdf
+
+
+.PHONY: docs-linkcheck
+docs-linkcheck:
+	poetry run make --directory docs/ linkcheck
+
+.PHONY: format
+format:
+	poetry run black ${SRC_FILES}
+	poetry run isort ${SRC_FILES}

doc-requirements.txt

@@ -6,14 +6,13 @@ Copies a a single from ``source`` to ``project``. Both should should have a vali
 .. code-block:: python
 
     collections = {
-      'my_files: {
+      'my_files': {
          'driver': 'copy_file',
          'source': '../extra_files/my_file.txt',
          'target': 'my_data/new_data.txt'
-         }
       }
-   }
+    }
 
 Clean up behavior
 -----------------
-During clean up the target file gets deleted.
+During clean up the target file gets deleted.

docs/drivers/copy_file.rst

@@ -11,14 +11,13 @@ Executes a function referenced by ``source`` and writes its return value into a
         return string
 
     collections = {
-      'my_files: {
+      'my_files': {
          'driver': 'function',
          'source': my_own_data,
          'target': 'my_data/my_file.txt'
          'write_result': True
          }
-      }
-   }
+    }
 
 The specified function gets 1 argument during the call: A dictionary which contains the complete configuration of the
 collection.

docs/drivers/function.rst

@@ -53,6 +53,7 @@ Using own drivers instead of e.g. a pure function call has several advantages:
             'source': '../tests/dummy/',
             'active': True,
         },
+    }
 
 If you have created an awesome driver, please consider to provide it to ``Sphinx-Collections`` by creating
 a PR on our `github project <https://github.com/useblocks/sphinx-collections>`_ .

docs/drivers/index.rst

@@ -9,12 +9,11 @@ collections have not been executed before this report gets generated.
 .. code-block:: python
 
     collections = {
-      'my_collection_report: {
+      'my_collection_report': {
          'driver': 'report',
          'target': 'reports/collections.rst'
-         }
-      }
-   }
+       }
+    }
 
 .. hint::
 
@@ -37,4 +36,4 @@ The following template is used to build the report:
 
 Clean up behavior
 -----------------
-During clean up the target folders, which contains the report, gets deleted.
+During clean up the target folders, which contains the report, gets deleted.

docs/drivers/report.rst

@@ -6,13 +6,12 @@ Copies a string defined in ``source`` into a file specified by ``target``.
 .. code-block:: python
 
     collections = {
-      'my_files: {
+      'my_files': {
          'driver': 'string',
          'source': 'Awesome, this is nice',
          'target': 'my_data/my_file.txt'
-         }
-      }
-   }
+        }
+    }
 
 You can also use more complex strings by assigning them to a variable.
 
@@ -33,13 +32,13 @@ You can also use more complex strings by assigning them to a variable.
     """
 
     collections = {
-      'my_files: {
+      'my_files': {
          'driver': 'string',
          'source': my_string,
          'target': 'my_data/my_file.txt'
-         }
-      }
-   }
+       }
+    }
+
 
 Clean up behavior
 -----------------

docs/drivers/string.rst

@@ -0,0 +1,3 @@
+sphinx>=3.4
+sphinxcontrib-collections
+gitpython

docs/requirements.txt

@@ -0,0 +1,46 @@
+import nox
+from nox_poetry import session
+
+PYTHON_VERSIONS = ["3.6", "3.8", "3.9.7"]
+SPHINX_VERSIONS = ["3.2", "3.5.4", "4.1", "4.2"]
+TEST_DEPENDENCIES = [
+    "pytest",
+    "pytest-xdist",
+    "responses",
+    "pyparsing!=3.0.4",
+    "requests-mock",
+]
+
+
+def is_supported(python: str, sphinx: str) -> bool:
+    return not (python == "3.6" and sphinx not in ["3.2"])
+
+
+def run_tests(session, sphinx):
+    session.install(".")
+    session.install(*TEST_DEPENDENCIES)
+    session.run("pip", "install", f"sphinx=={sphinx}", silent=True)
+    session.run("pip", "install", "-r", "docs/requirements.txt", silent=True)
+    session.run("echo", "TEST FINAL PACKAGE LIST")
+    session.run("pip", "freeze")
+    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 linkcheck(session):
+    session.install(".")
+    # LinkCheck cn handle rate limits since Sphinx 3.4, which is needed as
+    # our doc has to many links to github.
+    session.run("pip", "install", "sphinx==3.5.4", silent=True)
+
+    session.run("pip", "install", "-r", "docs/requirements.txt", silent=True)
+    session.run("make", "docs-linkcheck", external=True)