projects plugin sub-project watcher

[Blacksmoke16]

I have been working with the projects plugin and things have been working out quite well so far. However, I ran into a situation that I'm not sure is expected or not and wanted to create this discussion before going down the path of creating an actual issue for it.

My project is setup to leverage https://github.com/oprypin/mkdocs-gen-files as a means of generating documentation for source code files located in src/ of each project directory via https://github.com/mkdocstrings/crystal. I also setup the mkdocs feature watch to point to the project directory. When running mkdocs serve I can see that the non-source docs are successfully rebuilt and browser reloaded with my changes.

However if I were to make changes to the source code I can see a rebuild was triggered due to a change and the browser is refreshed:

INFO    -  Schedule build due to 'src/main.cr' in '.'
INFO    -  [21:26:26] Detected file changes
INFO    -  Building documentation...
INFO    -  Documentation built in 0.30 seconds

But the changes I made to the source file are not reflected. After some debugging I came to realize that they were reflected if I saved that project's mkdocs.yml file. Some additional debugging revealed that this seems to be because the mkdocs events that are emitted are different, seemingly because mkdocs.yml is special? mkdocs-gen-files is dependent on the files and page_content events that don't seem to be emitted when saving a source file.

So I guess the tl;dr is this a bug because the project file watcher is skipping this event? Or is this a feature request in that there could/should be a way to configure this? Or is this not even a mkdocs-material problem? I'm not familiar with the ecosystem so would appreciate any insights you have.

[squidfunk]

Thanks for reporting. I'd say this is a feature request, because we don't officially support the mkdocs-gen-files plugin (as it is not mentioned in our documentation), but we can definitely look into whether we can generally support plugins that add further files to the watched files. Note that this should in general be done in on_serve, as this is a discernable event for mkdocs serve, so we might need to add something to the projects plugin and/or the mkdocs-gen-files plugin. In any case, please create a feature request with a minimal reproduction that showcases the problem. We'll look into it then.

Another question: does it work with the mkdocs-monorepo- or -multirepo-plugins?

[squidfunk]

... I also hope I understood the situation correctly, but as mentioned, a reproduction saves a thousand words 😅

[Blacksmoke16]

@squidfunk Done! And I'm not sure, I'll have to see about getting one of those working to try it out.

#6945

EDIT: It doesn't seem like the monorepo one works at all. At least in the few min I been playing with it.