Open sksg opened 7 months ago
Thanks for opening the issue.
In addition to passing the arguments, we should consider how the script should read those arguments. sys.argv
may look like an obvious avenue, but it comes with a problem: mkdocs-gen-files would have to globally overwrite that value, run the script, then put it back. Which is messy and also now that I think about it, maybe some people rely on reading the top-level argv there 🤔
Maybe instead it will have to be something like mkdocs_gen_files.argv
.
What do you think? What's your expectation here?
Thanks for opening the issue.
No worries!
In addition to passing the arguments, we should consider how the script should read those arguments.
sys.argv
may look like an obvious avenue, but it comes with a problem: mkdocs-gen-files would have to globally overwrite that value, run the script, then put it back. Which is messy and also now that I think about it, maybe some people rely on reading the top-level argv there 🤔
In principle, I agree that we should not overwrite sys.argv
. I can't think of any real use case of reading the top-level argv, but I see your point. Looking at the docs for runpy.run_path
it seems that sys
is already altered by runpy.run_path
:
A number of alterations are also made to the sys module. Firstly, sys.path may be altered as described above. sys.argv[0] is updated with the value of path_name and sys.modules[name] is updated with a temporary module object for the module being executed. All modifications to items in sys are reverted before the function returns.
This seems to hint at further modifying sys.argv
is not such a bad option.
Maybe instead it will have to be something like
mkdocs_gen_files.argv
. What do you think? What's your expectation here?
I think a mkdocs_gen_files.argv
is not a bad option. It is clean and falls in line with the mkdocs_gen_files.open
way of using the plugin.
When I add scripts my_script_0.py
, my_script_1.py
, ... to the mkdocs.yml
, then in my head there is "shell" running a loop that invokes python my_script_n.py
. Following this line of thought, I would expect to find the arguments inside sys.argv
.
I would go for modifying sys.argv
. But I am completely fine with the mkdocs_gen_files.argv
approach as well. I leave it to you to decide want you think is best for your library.
Why
I like using gen-files, and I am using it with literate-nav in multiple projects. However, only 1-5 lines of the script code are unique to each project. These lines could easily be replaced by passing arguments to the scripts instead.
Proposal
Use white space to separate the arguments just like when invoking with python in the shell, e.g.
python3 docs/api_reference/.generate.py my_python_package
. An examplemkdocs.yml
:Similar to shell invocation, if the scripts themselves have spaces in their names you would need to quote the script, e.g. :
I think this is acceptable, since the user already is/should be wary of using spaces in file names.
With arguments passing, each of my projects would have identical scripts but unique arguments in the
mkdocs.yml
.Note that the beginning
.
in the script names is just to makemkdocs
not copy the python scripts over tosite
.