Support custom directories to watch when running mkdocs serve

[steven-terrana]

Implements #2632

• adds a watch property to the mkdocs.yaml schema. Accepts a list of directories to watch.
• adds a -w/--watch command line option to mkdocs serve that can be passed multiple times
• options from mkdocs.yaml and CLI flags are combined
• docs updated

[oprypin]

Thanks. Seems good overall.

[oprypin]

I think the path will have to be relativized to the location of mkdocs.yml, as here:

mkdocs/mkdocs/config/config_options.py

Lines 369 to 370 in 9880767

	if self.config_dir and not os.path.isabs(value):
	value = os.path.join(self.config_dir, value)

Well, I think that's what would be the most logical as per what I've seen from MkDocs so far.
Feel free to argue otherwise.

---

This would probably require a new type in config_optons.py. ListOfPaths or something.
During validation it could reuse FilesystemObject.

I would recommend turning it non-abstract:

 class FilesystemObject(Type):
+    existence_test = staticmethod(os.path.exists)
+    name = 'path'

Relevant implementation example:

mkdocs/mkdocs/config/config_options.py

Line 494 in 9880767

class Nav(OptionallyRequired):

---

Note that we probably should not check for existence of the path (exists=False should be kept). Not sure though.

[oprypin]

Update: we should, in fact, check for existence (just set exists=True), otherwise it throws an OSError anyway after startup

[oprypin]

To clarify why this is important:

watch:
    - foo

mkdocs serve --config-file=subdir/mkdocs.yml -w bar

I want this to watch the foo that is adjacent to mkdocs.yml.
The difference in the output being:

-Watching paths for changes: 'subdir/docs', 'subdir/mkdocs.yml', 'foo', 'bar'
+Watching paths for changes: 'subdir/docs', 'subdir/mkdocs.yml', 'subdir/foo', 'bar'

(-w flag not relativized intentionally)

[oprypin]

I'm leaving this to you btw.

And some tests for the new config option would be nice :D

[steven-terrana]

root@08e90cd25d84:/# mkdocs serve --config-file=mkdocs/mkdocs.yml -w home
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 1.09 seconds
INFO     -  [01:17:16] Watching paths for changes: 'mkdocs/docs', 'mkdocs/mkdocs.yml', 'mkdocs/foo', 'home'

seems to be working :).

agree this needs some tests. i'll have that soon. might take a day or two to carve out some more time.

[steven-terrana]

unit tests for ListOfPaths added

[pawamoy]

I'll argue in favor of this 🙂
As a data point, see this mkdocstrings issue.
That ListOfPaths type could be very useful to resolve it!

[pawamoy]

I'm not sure if/where it is stated in the docs that paths in the config file are relative to the config file itself. Maybe this could be added again in the docs for the watch option, and/or in the changelog, to make it clear?

[oprypin]

Looks good!

[steven-terrana]

I'm not sure if/where it is stated in the docs that paths in the config file are relative to the config file itself. Maybe this could be added again in the docs for the watch option, and/or in the changelog, to make it clear?

nice catch @pawamoy. I've updated the docs with a note admonition calling this out.

[oprypin]

Thank you!

[Andre601]

Bit late to the party, but what exactly would it then be? What would it's "position" be based of? Where the command is executed? That should've been mentioned here IMO, so maybe in a future PR/Commit could this be changed?