Add option to disable default watched dirs about mkdocs

[oprypin]

A plugin, if it really wanted to, can already use the unwatch function on the main directory.

I don't think this should be generally supported though.

There should be no need to physically copy files. #3451 will make it easier to express adding external files in terms of the File API, and later this could be taken further - to make it easier to include whole directories and possibly not require writing any code.

[pawamoy]

Before opening a PR, please wait a bit for other maintainers opinion 🙂
I'll tag some of them in case they'd like to chime in: @oprypin @ultrabug

[pawamoy]

Great, so we can simply hook into on_serve (in a plugin or a simple hook) and use server.unwatch("path/to/directory"). Since there's an easy hook-based solution for this, and future changes that can make this even easier, I'll close this issue. Thanks @oprypin!

[pedro-psb]

here should be no need to physically copy files. #3451 will make it easier to express adding external files in terms of the File API, and later this could be taken further - to make it easier to include whole directories and possibly not require writing any code.

That looks great, thanks for sharing. I'll consider using the File api in the future.

Great, so we can simply hook into on_serve (in a plugin or a simple hook) and use server.unwatch("path/to/directory")

That worked well for me. Thanks for the additional links, they were very helpful.

[pawamoy]

Hello!

Does this temp dir being watched cause you issues? Which ones?

How do you aggregate files? With a custom script before using MkDocs, or with a plugin hook?

[pedro-psb]

Does this temp dir being watched cause you issues? Which ones?
How do you aggregate files? With a custom script before using MkDocs, or with a plugin hook?

The tempdir being watched causes an infinite reload problem. I set the real docs-source to be watched and, when something changes there, a plugin hook (I actually use mkdocs_macro hooks) copies that to the tempdir, which is also being watched

It's not obvious why this recurses (I think it should stop reloading after the second trigger) and maybe I can find a way of preventing that in my code, but that simply doesn't happen if I disable watching tempdir in the first place.

[pawamoy]

Yes I see what you mean. So, if I understand correctly, you add source directories to the watch list, and it lets you copy all relevant files from these folders (thanks to some mkdocs-macros magic) into a final but temporary docs directory, from which the site is built. Since this temporary docs directory is the one assigned to docs_dir, it's automatically added to the watch list. But changes only occur in this directory when they first occur in the real source ones, so it doesn't make sense to watch it.

So, the feature makes sense to me (having more control over what is watched) and would surely help other users (this is not the first time someone experiences that). But let me try to describe an alternative first. I don't want to convince you it is a better alternative, I just want to lay it out here for future reference and completeness 🙂

There is a way to add files to the source docs directory without triggering a reload. MkDocs API allows to add files without actually copying them to the docs source folder. That's what the mkdocs-gen-files plugin does: it creates files in a temporary directory (not in the docs sources), and uses MkDocs' API to "register" these files as if they were in the docs sources. I believe it is possible to use a similar approach for your use-case, or maybe even use mkdocs-gen-files directly.

Let say you have a list of source folders: ["/path/to/source1", "/path/to/source2"]. You want to copy all files within these sources into the final docs directory docs. You'd configure mkdocs-gen-files like this:

plugins:
- gen-files:
    scripts:
    - copy_sources.py

And you would write the copy_sources.py script like this:

from pathlib import Path
import mkdocs_gen_files

sources = [Path("/path/to/source1"), Path("/path/to/source2")]

def recursive_copy(source: Path, directory: Path):
    for each in directory.iterdir():
        if each.is_dir():
            recursive_copy(source, each)
        else:
            with mkdocs_gen_files.open(each.relative_to(source), "wb") as file:
                file.write(each.read_bytes())

for source in sources:
    recursive_copy(source, source)

(not tested, but it shouldn't be far from working 🙂)

With this, each build would "replicate" all the files and folders from your real sources into the final docs directory, without triggering reload when there are changes in docs (unless you actually write into it through other means).

[pedro-psb]

Thanks for pointing out this alternative, I might give it a try.
And since the feature seems to make sense, I should open a PR shortly.