mkdocs 1.2.x livereload no longer working

[GordonMcKinney]

mkdocs==1.2 and latest no longer works
mkdocs==1.1.2 works

MacOS 11.4
Docker version 20.10.7, build f0df350
python:3.8-alpine (3.9.5 and 10-rc same behavior)

I checked the Docker container and the markdown is updating but the generated html is not. This seems to be associated with the 1.2 change with watcher.

LMK what logs/config/diag I can provide to help RCA the issue.

[pawamoy]

Ah, I recently experienced issues with watchdog + Docker/Kubernetes setups. Basically the observer based on inotify is a bit limited on Docker setups, I did not dig deep into it but it seems the inotify events on directories within a volume are only available to one container. I solved it by using the observer that polls the file system instead. Do you happen to have your docs files in a volume mounted on several containers?

[GordonMcKinney]

We mount our source docs to /tmp in the container. We do have several containers that run this way but we observed the issue in a singleton environment (compose down, prune, and a single compose up).

Happy to help troubleshoot. LMK.

[pawamoy]

Could you try to add "dependencies" (not sure if this is the right term) to your docker-compose configuration so as to make sure the container running MkDocs starts last, and tell us if livereload still does not work?

[GordonMcKinney]

I understand now. The docker compose has a single container only.

In summary, I see the markdown update but not the HTML file change when observed inside the container with docker exec -it /bin/sh

I tested with mkdoc -v serve and saw no output after a change.

[squidfunk]

Users of Material for MkDocs are also reporting this new behavior, i.e. mkdocs serve not working properly. It would be great if we could somehow ensure that it also works from within Docker, because many users use the Docker image for previewing.

[pawamoy]

A quick test would be to patch https://github.com/mkdocs/mkdocs/blob/master/mkdocs/livereload/__init__.py#L65 to use PollingObserver instead of Observer to see if it fixes the issue.

from watchdog.observers.polling import PollingObserver

[ultrabug]

@oprypin hi, what's your point of view on this please mate?

[imolavirus]

A quick test would be to patch https://github.com/mkdocs/mkdocs/blob/master/mkdocs/livereload/__init__.py#L65 to use PollingObserver instead of Observer to see if it fixes the issue.

from watchdog.observers.polling import PollingObserver

I'm using docker compose with a single container and this patch fixed the issue for me.

[oprypin]

Does reproducing this issue require running MkDocs in Docker on Mac? Or are there perhaps other conditions to this?

I don't know how to reproduce it, because just running in Docker on Linux works.

[imolavirus]

I saw the issue when running Docker on Windows, with the docs files mounted from the Windows file system.

However, using Docker on WSL2 with the docs files mounted from the Linux file system, I'm not able to reproduce the issue.

[stevejr]

I am running Docker on Mac and see this issue too. Some initial logs:

INFO - Documentation built in 51.21 seconds DEBUG - [13:26:54] Watching directory '/docs/docs' DEBUG - [13:26:54] Watching file '/docs/mkdocs.yml' through directory '/docs' INFO - [13:26:54] Serving on http://0.0.0.0:8000/ DEBUG - [13:26:56] "GET /livereload/47543439/47625824 HTTP/1.1" code 200

We run the docker container as follows:

docker build -t mkdocs-serve-local:latest mkdocs/ && docker run --rm -it -p 8000:8000 -v ${PWD}:/docs mkdocs-serve-local:latest

The Dockerfile CMD is CMD ["serve", "-v", "--dev-addr=0.0.0.0:8000"]

These are the dependencies we use when building the image:

mkdocs==1.2.1
Pygments>=2.4 
markdown>=3.2 
pymdown-extensions>=7.0 
mkdocs-material-extensions>=1.0
mkdocs-git-revision-date-localized-plugin>=0.7.3 
mkdocs-material>=7.1.8

[oprypin]

I have a proposed fix in #2477.
I did not figure out any hybrid approach that would let us still benefit from the fast implementation in most cases.

Please try it and let me know if something's wrong.

pip install git+https://github.com/mkdocs/mkdocs.git@refs/pull/2477/head

[GordonMcKinney]

@oprypin, I can confirm git+https://github.com/mkdocs/mkdocs.git@refs/pull/2477/head fixes the issue in docker compose on MacOS.

[oprypin]

The fix is now included in the latest release.

[samuelcolvin]

Time for mkdocs to move to watchfiles ? 👀

(Admission: watchfiles is me)