Unable to run script with arguments

[ssbarnea]

I am currently running a command to produce documentation and I observed that is not possible to pass arguments.

  - gen-files:
      scripts:
        - python3 -m ansiblelint -L -f docs

[oprypin]

mkdocs-gen-files does not run arbitrary shell commands at all.

If you want to use its ability to generate files, you need to write that as a Python script. (which can then call a subprocess or whatever is desired).

To just run custom code, you can more directly utilize mkdocs' hooks feature.

---

Regarding your specific command: this is just a lint feature, I wouldn't recommend integrating it with mkdocs because it just adds time to builds (even live rebuilds) - just run it separately or in a wrapper.

mkdocs_gen_files is not applicable even more so.

---

If you do however, still want to run a lint check, you could write a custom hook inspired by mkdocs-code-validator plugin.

https://github.com/oprypin/mkdocs-code-validator/blob/586842aa7e72d08d4cc61c1bf3644a3fe109b344/mkdocs_code_validator/plugin.py#L100-L113

Make a hook file that starts a subprocess in on_pre_build and gets results from that subprocess only in on_post_build. That will run in the background and can avoid slowing down your build.

[llucax]

Hello @oprypin, sorry for reliving the dead, but before opening a new issue I just wanted to check if there is any intention to support this given my use case.

To generate API reference pages, we are using a script based on the recipe provided in https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages:

• https://github.com/frequenz-floss/frequenz-sdk-python/blob/v0.x.x/docs/mkdocstrings_autoapi.py

We have many projects and we would like to provide one script for all of them for maintainability reasons, so it would be nice to be able to ship this script in another python package and then in the mkdocs.yml do something like:

plugins:
  - gen-files:
      scripts:
        - python -m frequenz.repo.config.mkdocs

(and maybe pass some arguments too, so we can allow projects to eventually customize how the script is run (for example, if they need to discover source files in a directory different to the default src, but providing a Python file instead would be difficult because the python file will live in a separate package installed via pip).

Without this, the alternative is to add to every project a wrapper script that will just import frequenz.repo.config.mkdocs, which is of course doable but a bit annoying.

Would you recommend to use the plain mkdocs hook for generating the API pages too? If so, what is the reason for proving a way to run scripts in mkdocs-gen-files at all if it can be done with mkdocs hooks?

Thanks!