PyCharm File Watchers for Sphinx projects#
I often have the case that I want to see my documentation as fast as possible.
And I know there are “Preview” IDE-Extensions available, which want to solve this problem.
But the all have one of the following problems:
they often support standard rst-syntax only (so no Sphinx-Extension support).
their preview window is not reachable or positioned they way I need it.
they often force a full build, as their build command is different as the one I normally use.
I need to see the result in a normal browser window with the option to “debug” the site (e.g. to check css configs).
So I came up with the solution to use the build-in File Watcher feature of my PyCharm IDE.
Open File -> Settings -> File Watchers
Create a new watcher (
plus sign) and select
File Type to
Configure the project
scope. This defines when your watcher gets triggered.
docs folder and press
Then select the
_build folder inside
docs and exclude it by pressing
This step is important, otherwise the File watcher will hang in a loop, as it is changing files under
what would retrigger the watcher.
Back to the File Watcher configuration.
sphinx-build command from your used Python Environment.
Set as arguments
-b html . _build/html and as
Working Directtory the
Advanced Options select
This helps to see each build result.
After storing the config by pressing
OK, a small popup shows up in the bottom right corner, asking you to
trust all project file watchers in general.
That’s it. For sure, you still need to open the generated page in your browser by hand.
How to configure and use PyCharm file watchers to generate Sphinx documentation with ech file change