Does not work under macOS Mojave

[elmar-hinz]

Saving triggers a reload of the internal browser, but it does not trigger a re-built of the HTML. External browsers show the outdated HTML, too. Not even a restart of the container securely triggers a new built.

November 2018 on macOS Mojave

Digging a little deeper. The Sphinx-Server is working, if I start it from the command line like given in its documentation:

docker run -itd -v "$(pwd)":/web -u $(id -u):$(id -g) -p 8000:8000 --name sphinx-server dldl/sphinx-server

When I edit the files and save them, the change watcher works and rebuilds the HTML. I can follow this in the console of Kitematik. I can call the changed HTML with any Browser.

[I 181124 20:39:37 server:298](B Serving on http://0.0.0.0:8000
[I 181124 20:39:37 handlers:59](B Start watching changes
[I 181124 20:39:37 handlers:61](B Start detecting changes
[I 181124 20:39:47 handlers:132](B Browser Connected: http://127.0.0.1:8000/Architektur.html
+--------- Architektur.rst changed ----------------------------------------------
| Running Sphinx v1.8.2

When I start the Server from within the Atom Editor it does not work any longer. It just does not detect the change. It also comes under the container name: Sphinx-Preview. The only difference I see is in the ports:

CONTAINER ID        IMAGE                COMMAND                  CREATED             STATUS              PORTS                                              NAMES
958b2f7614eb        dldl/sphinx-server   "python /opt/sphinx-…"   3 minutes ago       Up 58 seconds       0.0.0.0:8000->8000/tcp, 0.0.0.0:35729->35729/tcp   sphinx-preview

CONTAINER ID        IMAGE                COMMAND                  CREATED             STATUS              PORTS                               NAMES
c1fb5d789a70        dldl/sphinx-server   "python /opt/sphinx-…"   5 seconds ago       Up 3 seconds        0.0.0.0:8000->8000/tcp, 35729/tcp   sphinx-server

The Workaround

This brings me to the workaround to start the container from outside as 'sphinx-preview' like so or just start it from within Kitematik.

docker run -itd -v "$(pwd)":/web -u $(id -u):$(id -g) -p 8000:8000 --name sphinx-preview dldl/sphinx-server

The latency between saving and building is about 10 seconds. This is too slow to be really satisfying and yet it is the best setup for authoring I have seen so far. Drive it forward and we will get better docs in the future.

How about a docker container, that renders Sphinx in high quality with a LaTeX setup to PDF?

[quentinus95]

Thanks for digging into the issue. Using docker container inspect, you may find some other differences between the containers which can't be seen using docker ps.

About rendering LaTeX files, the main issue is the size of the docker image, which would be extremely high. The best solution for now is to use the image to generate a tex file, and compile it using pdflatex outside of the container.

We worked some time ago on a self-hostable compiling service to allow compiling tex files without LaTeX installed (see dldl/sphinx-server#27) but did not have the time to finish the work.

[quentinus95]

Also notice that the port 35729 is actually not used as stated by @hileef in dldl/sphinx-server#13.

[hileef]

Hi all,

Given I have a fresh install of macOS Mojave, I have attempted to reproduce the issue, however I am not succeeding in doing so. I have installed the atom editor, the browser-plus and sphinx-preview packages, and have tried to edit and save .rst files from within atom and successfully see the updated HTML in the internal browser.

However, I did notice that there is a difference in configuration when the server is launched from the command line or from the sphinx-preview plugin : the user and group specification.

Maybe this is related ? In order to make sure, @elmar-hinz , could you please try the following command and tell us if you still encounter the issue of the server not detecting file changes :

docker run -itd -v "$(pwd)":/web -p 8000:8000 --name sphinx-preview dldl/sphinx-server

If that is the case, then it probably means that the issue comes from not specifying the user and group when launching the container from the sphinx-preview plugin.

[hileef]

Okay so after further testing, I have managed to encounter the issue as mentioned by @elmar-hinz .

The behaviour of python-reload is quite erratic, as it "appears" that there were no filesystem changes even though docker exec -it sphinx-preview cat index.rst does show the updated content. Interestingly, when starting another sphinx-server container on the same folder, python-reload from the original sphinx-preview container does pickup the changes...

So, from what I can see, it looks like a weird filesystem event issue that may be related to either the docker engine itself or the darwin kernel.

Either way, based on a few docker inspect runs, I have managed to not meet the problem anymore with these patches : #16

[quentinus95]

@Coac was it released to a new version?

[Coac]

Published in v0.1.3 👏