Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MkDocs build from template broken #515

Open
matt-graham opened this issue Feb 7, 2025 · 0 comments · May be fixed by #517
Open

MkDocs build from template broken #515

matt-graham opened this issue Feb 7, 2025 · 0 comments · May be fixed by #517
Labels
bug Something isn't working

Comments

@matt-graham
Copy link
Collaborator

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
@matt-graham matt-graham added the bug Something isn't working label Feb 7, 2025
@matt-graham matt-graham linked a pull request Feb 10, 2025 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant