Feature request: Passing arguments to the scripts.

[sksg]

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 example mkdocs.yml:

...
plugins:
  - gen-files:
      scripts:
        - docs/.index.py my_main_readme_file my_contributing_file my_install_file
        - docs/api_reference/.generate.py my_python_package
        - docs/examples/.generate.py my_examples_folder
...

Similar to shell invocation, if the scripts themselves have spaces in their names you would need to quote the script, e.g. :

...
plugins:
  - gen-files:
      scripts:
        - "\"docs/api_reference/.generate the api.py\" my_python_package"
...

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 make mkdocs not copy the python scripts over to site.

[oprypin]

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?

[sksg]

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.