Fix MkDocs build from template instances (#517)

Resolves #515 

- Updates `mkdocs.yml` configuration in template to use structure
required by current MkDocs.
- Fixes TOML `tox` configuration for `docs` environment to use required
array of arrays syntax.

Leaving this as a draft for now as we probably want to add a test for
building MkDocs site from a template instance to catch things like this
in future, ideally by running `tox -e docs` as well as `mkdocs build` to
also catch error in `tox` configuration. I am not sure whether we would
want to add `tox` as a development dependency here, or create a
temporary virtual environment as suggested also in #516, install `tox`
there and test running `tox -e docs` (plus potentially default test
environment)?

Author: matt-graham

tests/data/test_package_generation/mkdocs.yml

@@ -47,10 +47,10 @@ plugins:
       default_handler: python
       handlers:
         python:
-          docstring_style: google
-          import:
+          inventories:
             - "https://docs.python.org/3/objects.inv"
           options:
+            docstring_style: google
             show_submodules: true
           paths: [src]
   - include-markdown:

tests/data/test_package_generation/pyproject.toml

@@ -127,9 +127,11 @@ env_run_base = {commands = [
     "test",
 ]}
 env.docs = {commands = [
-    "mkdocs",
-    "build",
-    "--strict",
+    [
+        "mkdocs",
+        "build",
+        "--strict",
+    ],
 ], extras = [
     "docs",
 ]}

tests/test_package_generation.py

@@ -128,7 +128,7 @@ def test_pip_installable(
 def test_optional_funder(
     tmp_path: pathlib.Path, generate_package: typing.Callable, funder: str
 ) -> None:
-    """Test package generation."""
+    """Test specifying funder or not in package generation."""
     config = {
         "github_owner": "test-user",
         "project_short_description": "description",
@@ -149,3 +149,32 @@ def test_optional_funder(
             f"## Acknowledgements\n\nThis work was funded by {config['funder']}."
             in readme_text
         ), readme_text
+
+
+def test_docs_build(
+    tmp_path: pathlib.Path,
+    venv: pytest_venv.VirtualEnvironment,
+    generate_package: typing.Callable,
+) -> None:
+    """Test documentation build from package created from template."""
+    config = {
+        "github_owner": "test-user",
+        "project_short_description": "description",
+        "project_name": "Cookiecutter Test",
+    }
+    generate_package(config, tmp_path)
+    test_project_dir = tmp_path / "cookiecutter-test"
+    venv.install("tox")
+    tox_docs_process = subprocess.run(  # noqa: S603
+        [
+            pathlib.Path(venv.bin) / "tox",
+            "-e",
+            "docs",
+        ],
+        cwd=test_project_dir,
+        capture_output=True,
+        check=False,
+    )
+    assert tox_docs_process.returncode == 0, (
+        f"Something went wrong with building docs: {tox_docs_process.stderr!r}"
+    )

{{cookiecutter.project_slug}}/mkdocs.yml

@@ -47,10 +47,10 @@ plugins:
       default_handler: python
       handlers:
         python:
-          docstring_style: google
-          import:
+          inventories:
             - "https://docs.python.org/3/objects.inv"
           options:
+            docstring_style: google
             show_submodules: true
           paths: [src]
   - include-markdown:

{{cookiecutter.project_slug}}/pyproject.toml

@@ -133,9 +133,11 @@ env_run_base = {commands = [
     "test",
 ]}
 env.docs = {commands = [
-    "mkdocs",
-    "build",
-    "--strict",
+    [
+        "mkdocs",
+        "build",
+        "--strict",
+    ],
 ], extras = [
     "docs",
 ]}