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


File Watchers area on the Settings window#

Create a new watcher (plus sign) and select <custom>.


File Watcher template selection#

Set File Type to All.

Configure the project scope. This defines when your watcher gets triggered.

Select your docs folder and press Include recursively.

Then select the _build folder inside docs and exclude it by pressing Exclude recursively. This step is important, otherwise the File watcher will hang in a loop, as it is changing files under _build, what would retrigger the watcher.


Project scope defintion#

Back to the File Watcher configuration.

Select for Program the sphinx-build command from your used Python Environment.

Set as arguments -b html . _build/html and as Working Directtory the docs/ folder.

Under Advanced Options select Always for Show console. This helps to see each build result.


Project scope defintion#

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.


Trust File Watchers?#

That’s it. For sure, you still need to open the generated page in your browser by hand.


comments powered by Disqus