On Sat, Jan 28, 2023 at 10:48 PM Stephen J. Turnbull < stephenjturnbull@gmail.com> wrote:
Odhiambo Washington writes:
from mailman_web.settings.base import * from mailman_web.settings.mailman import *
I think just putting these as close to the top as possible, and including a comment (or two) saying that this is importing defaults that can be overridden by any assignment made later in the file is about as far as we can go for explaining. If you don't know how Python imports work, just ask about the specific case. There's quite a bit of potential complexity hiding in those '.'s; much more complicated than the '/'s in a file system path. Trying to explain the ins and outs of the Python import system is way beyond the scope of Mailman docs.
[At first instance, it is not obvious that mailman_web.settings.base and mailman_web.settings.mailman are actually paths in Python - which magically translates to mailman_web/settings/base.py and mailman_web/settings/mailman.py]
You shouldn't have to know that, it doesn't help with the bigger problem of finding mailman_web, and any simple explanation might turn out not to be true in your installation. This is why I prefer flat files for end-user configuration, even if they get pretty big. I understand why developers do stuff like this, but it's not "naive user"-friendly.
For example, my mind all along has been tuned to having a settings_local.py for overriding the settings.py.
Yes, and that is a better system unless our intent is to *hide* settings from the user, in my opinion. I don't see why you chose to deviate from it. Either way you have to integrate settings you have changed with settings the developers have changed. It's easier if you stick with the system you're most familiar with.
However, with this particular documentation, it would appear that everything is intended to just go into /etc/mailman3/settings.py.
Is it possible to modify the documentation
Which documentation? We can modify our own, but that's a pretty big task because we have several different systems for managing config files over the last five or ten years. We shouldn't mandate any particular organization because they all still work, and people who use older setups shouldn't have to do without our docs. And we can't do anything about out-of-date mirrors or HOWTOs by random admins on the web.
and that those settings are in what file(s) ?
But we don't know where those files are. If you use a venv install, they're almost certainly in $MAILMAN_HOME/venv/lib/python3.N/site-packages/mailman_web/settings/, but otherwise the mailman_web/settings part could be anywhere on Python's search path. And on modern systems unless you have a dedicated host with everything installed at once, you're likely to have 3 or more Pythons installed (Python 2.7, and two or more Python 3s). So tools like find and grep -l are often more confusing than enlightening.
I think if you get confused, the most efficient solution is to just ask. If Mark or I or whoever directs you to check out the defaults, and you can't find them, ask again.
Steve
All the above noted, and well-received. I only decided to experiment with this particular documentation because it is the *OFFICIAL* one. And to be honest, I am yet to wrap my head around everything, so I still have a lot of questions in my head. Will be seeing you often :)
-- Best regards, Odhiambo WASHINGTON, Nairobi,KE +254 7 3200 0004/+254 7 2274 3223 "Oh, the cruft.", egrep -v '^$|^.*#' ¯\_(ツ)_/¯ :-)