search

canonical / sphinx-docs-starter-pack

A documentation starter-pack
https://canonical-starter-pack.readthedocs-hosted.com/
Other
13 stars 35 forks source link

Star import of custom_conf.py fails to validate #167

Closed rkratky closed 7 months ago

rkratky commented 7 months ago

The current setup uses

from custom_conf import *

which is flagged as problematic by various Python linters, including pyflakes. This is called 'star import' and is generally discouraged (https://www.geeksforgeeks.org/why-import-star-in-python-is-a-bad-idea/). More importantly, such setup won't validate when a repo uses a Python linter that fails on detecting a star import (https://www.flake8rules.com/rules/F405.html).

An alternative to the current setup would be to use conf.py only but with a clear separation of 'default' and 'custom' areas.

ru-fu commented 7 months ago

We'll go back to using conf.py without includes when we change the starter pack to an extension. I don't see a need to do another big impact change before that - if teams have problems with linters with the current setup, they can go for the one-file solution (which will impact only them, not every team).