Documentation does not update on changes to code/theme/static files

[rouge8]

Extracted from my comment on #31: When I save, it triggers the rebuild as expected, but the built content is not actually changed.

Command:

sphinx-autobuild -E -a -z /Users/rouge8/rj/fathom-assets/fathom_assets -n -b html -d /Users/rouge8/rj/fathom-assets/.tox/docs-dev/tmp/doctrees . _build/html

Output:

+--------- ../fathom_assets/query/managers.py changed ---------------------------
| Running Sphinx v1.3.1
| loading intersphinx inventory from https://docs.python.org/2.7/objects.inv...
| building [mo]: all of 0 po files
| building [html]: all source files
| updating environment: 3 added, 0 changed, 0 removed
| reading sources... [ 33%] api
| reading sources... [ 66%] index
| reading sources... [100%] queries
|
| looking for now-outdated files... none found
| pickling environment... done
| checking consistency... done
| preparing documents... done
| writing output... [ 33%] api
| writing output... [ 66%] index
| writing output... [100%] queries
|
| generating indices... genindex py-modindex
| highlighting module code... [ 25%] fathom_assets.query.managers
| highlighting module code... [ 50%] fathom_assets.query.terms
| highlighting module code... [ 75%] fathom_assets.query.query
| highlighting module code... [100%] fathom_assets.query.nodes
|
| writing additional pages... search
| copying static files... done
| copying extra files... done
| dumping search index in English (code: en) ... done
| dumping object inventory... done
| build succeeded.
+--------------------------------------------------------------------------------

+--------- ../fathom_assets/query/managers.py changed ---------------------------
| Running Sphinx v1.3.1
| loading intersphinx inventory from https://docs.python.org/2.7/objects.inv...
| building [mo]: all of 0 po files
| building [html]: all source files
| updating environment: 3 added, 0 changed, 0 removed
| reading sources... [ 33%] api
| reading sources... [ 66%] index
| reading sources... [100%] queries
|
| looking for now-outdated files... none found
| pickling environment... done
| checking consistency... done
| preparing documents... done
| writing output... [ 33%] api
| writing output... [ 66%] index
| writing output... [100%] queries
|
| generating indices... genindex py-modindex
| highlighting module code... [ 25%] fathom_assets.query.managers
| highlighting module code... [ 50%] fathom_assets.query.terms
| highlighting module code... [ 75%] fathom_assets.query.query
| highlighting module code... [100%] fathom_assets.query.nodes
|
| writing additional pages... search
| copying static files... done
| copying extra files... done
| dumping search index in English (code: en) ... done
| dumping object inventory... done
| build succeeded.
+--------------------------------------------------------------------------------

[I 150904 01:55:34 handlers:91] Reload 1 waiters: None
[I 150904 01:55:34 handlers:131] Browser Connected: http://127.0.0.1:8000/api.html#module-fathom_assets.query.managers

[Ramblurr]

Its not just code affected by this but static resources like css too.

[ebw44]

I've got a similar issue with sphinx.ext.todo. The .. todolist:: doesn't get updated if the rst file that contains it is not modified and you only add a .. todo:: in another file. I suppose sphinx-autobuild is building only files that have changed, it can however update references from toctree, so it would be great if it could also work for todo.

PS: Thanks for the great tool by the way.

[SunbrightShinobi]

I have a similar issue with .jinja files. autobuild detects the update to the Jinja file but has no knowledge to drive a rebuild of the .rst file(s) that uses it, so the actual document doesn't update. I have to just resave the .rst file to update. That works for one .rst file but not if the template is used in multiple different .rst files.

[pradyunsg]

This seems to be caused by https://github.com/sphinx-doc/sphinx/issues/2090 -- Sphinx itself isn't handling such changes correctly in incremental builds.

Looks like fixing upstream might be easier than working around this behavior locally. I'll look into this, hopefully soon-ish.

[pradyunsg]

This behaviour is now documented under https://github.com/GaretJax/sphinx-autobuild#relevant-sphinx-bugs. I'm not going to be able to contribute a patch to fix this upstream (it's a lot more involved that I can do), but for the time being, I think this documentation-only fix is sufficient.

If someone has any suggestions for how we can workaround this issue more transparently, while not being a big maintainance burden, I'm all ears. :)

[pradyunsg]

Going to go ahead and close this now as a wontfix, since I genuinely don't think that there's anything that can be done at the level of this tool to fix this issue.

If someone does think there is something we can do, please feel free to drop a comment here. It's not like closed issues can't be reopened. :)

[linusmarco]

It appears that the underlying issue is at least partially fixed! Now I get automatic rebuilds and browser reloads when I update my code files (as long as the directory they're in is watched). Still no reloads for other static files, but the code files were the biggest pain point since that's where most of the docs live for many of us using autodoc.

@pradyunsg