Skip to content

MkDocs build from template broken #515

@matt-graham

Description

@matt-graham

Describe the Bug

While using template to create https://github.com/UCL/causalprog I came across a few issues with building MkDocs site

  • The TOML tox specification of the docs environment uses the wrong syntax for specifying the commands to run - there should be an additional set of square brackets as commands is expected to be an array of arrays, each inner array corresponding to a single command (potentially consisting of multiple components).
  • Our mkdocs.yml configuration in the template is out of date with current MkDocs - specifically, inventories should now be specified with inventories rather than imports key, and docstring_style should live under handlers.python.options

Changes required to template are equivalent to those in
https://github.com/UCL/causalprog/compare/0e4d06c..130dbaa

To Reproduce

Create an instance of template and run tox -e docs or mkdocs build

Expected Behaviour

No errors when attempting to build documentation site locally or on GitHub Actions

Actual Behaviour

A series of errors (first one from tox TOML config problem, latter two from mkdocs.yml issues

TypeError: 'mkdocs' is not list

TypeError: PythonConfig.__init__() got an unexpected keyword argument 'docstring_style'

INFO    -  FutureWarning: The 'import' key is renamed 'inventories' for the Python handler
             File "causalprog/.tox/docs/lib/python3.13/site-packages/mkdocstrings/handlers/base.py", line 680, in get_handler
               self._handlers[name] = module.get_handler(**kwargs)
             File "causalprog/.tox/docs/lib/python3.13/site-packages/mkdocstrings_handlers/python/handler.py", line 361, in get_handler
               warn("The 'import' key is renamed 'inventories' for the Python handler", FutureWarning, stacklevel=1)

Version In Use

v1.0.0-31-ga3003e2

Additional Context

- Cookiecutter version: 2.6.0
- Operating system: Ubuntu
- Python version: 3.13.0

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions