Issue with main.py requirements

[boromir674]

If there is a top-module level main.py ie at src/my_package_name/main.py then when running mkdocs build with the macros plugin enabled, then the process fails with

NameError: None of the standard functions was found in module 'main':
['define_env', 'on_pre_page_macros', 'on_post_page_macros', 'on_post_build']

unless one of 'define_env', 'on_pre_page_macros', 'on_post_page_macros', or 'on_post_build' is declared on main.py.

But this looks like a bug. Why force someone, who opted for that design, to add macros-specific code into there main business log?

[github-actions[bot]]

Welcome to this project and thank you!

[fralau]

Thanks for your remark. I am not sure I understand your question: if you have a main.py file, what else could be in that file (by design) other than one at lest of those four functions?

The purpose of that error message is to detect a malformed file.

Conversely, if one doesn't want to write any macro or ad-hoc code, the best is to not create a main.py file.

[wryfi]

@boromir674 you can set the module name in mkdocs.yml to something else, like so:

plugins:
  - macros:
      module_name: custom_mkdocs

Then write your module in custom_mkdocs.py instead of main.py. The module still has to be at the top level of your project though, and I dislike this design choice.

@fralau I don't think it's very user friendly to:

1. make the root level main.py the default place to extend this plugin, since this is often the entry point for application logic; or
2. force users to put their custom code in the root level of the repo.

I don't want a python module that is unrelated to application logic at the top level of my project. It is confusing. Both the location of the module and its name should be configurable.

(For the record, I don't like having mkdocs.yml at the top level of my repo either. I want all of my documentation related files isolated in my docs directory.)

Such things should always be configurable.

[fralau]

@boromir674 Thank you for your comment.

Indeed, you can redefine the module name. Actually you can also indicate a relative path (scripts/custom_mkdocs), if you wish, so you can put it any subdirectory you prefer (some projects do that, for the reasons you said).

If I were in the same position as you, I would certainly do that.

For the design choice, I understand your point. I went for simplicity, to make things easiest possible for first-time users with small projects; but giving more advanced (and responsible) admins of large projects the ability to set things exactly as they prefer.

[wryfi]

Ah, thank you for clarifying that @fralau! It's not very clear from the docs that you can give a full filesystem path to the module.

[fralau]

Thanks! In my view, it was fairly explicit:

Name of the Python module containing macros, filters and variables. Indicate the file or directory, without extension; you may specify a path (e.g. include/module). If no main module is available, it is ignored.