Development notes

Local http-server solution

I would like to implement the same functionality I have with the mkdocs serve command, that is, I would like that my modifications in markdown files to be reflected immediately in the static web page that was being served by the http-server created by mkdocs.

The solution I come up with was to use the entr (Event Notify Test Runner) application. The idea is simple, I wrap the http-server (simple node.js using express framework) and the file-monitor scripts using entr in a Docker image. Then I create two containers from that image, one running the http-server and the other running the file-monitor.

Notice that I could host the Docker containers in an external server (capitu) and create services for it with docker-compose that could be easily started and stopped. As it is done with my other applications.

However, there are some issues with entr in Docker for Mac that makes this solution to fail.

Docker for Mac issue for entry

It seems that there is an incomplete support of inotify(7) (one of the system commands on which entr is built; the other one being kqueue(2)). This issue kills the ability of entr to identify modification in files.

The workaround suggests to add the environment variable ENTR_INOTIFY_WORKAROUND in the Dockerfile. Existing files are now identified when changed. But whenever we have a modification on the directory structure, entr does nothing. Normal behaviour would be to exit.

This issue makes the Docker container solution not feasible since we are not going to have automatic web-page reconstruction after a file creation, for example.

Therefore, I added the flag --with-http-server in the build subcommand of journal-manager. This flag will create an http-server in the same location specified for the build; it will start the http-server and start monitoring the journals files. The only restriction to this approach is that we have to restart the build process if we create a new journal.

This is enough to recover the nice feature of immediate update. It works locally, though. In order to update the journals content in the external server, I need to set up a cron job to rebuild the journals, let us say, every day in the morning.

Notes about style

I am trying to follow some of the guidelines described in the Google Python Styleguide.

Code snippets

def peek_is_empty(iterable: Iterable(Any)):
    '''
    Check if an iterable is empty without advancing the iterator.
    '''
    try:
        first = next(iterable)
    except StopIteration:
        return True, iterable

    return False, itertools.chain([first], iterable)