Building docs only work the first time (for non-doc modifications)

[ewjoachim]

SUMMARY

Maybe I missed something but, (probably depending on the changes you make,) tox -e build-docs only builds the doc the 1st time. Then, it relies on .tox/.tmp/.doctrees, and will read the source again only if a non-changelog-fragment rst file was modified.

ISSUE TYPE

• Bug Report

PYLISSH and LIBSSH VERSION

457c1e6 and libssh is irrelevant

OS / ENVIRONMENT

Not sure anything is relevant here, but if need be, MacOS.

STEPS TO REPRODUCE

$ tox -e build-docs
$ echo "Hey **there**" > docs/changelog-fragments/12.mist.rst
$ tox -e build-docs

EXPECTED RESULTS

On the second build, the changelog fragment should appear

ACTUAL RESULTS

It doesn't

CAUSED BY

Sphinx relies on .tox/.tmp/.doctrees. If it exists and (I assume) docs rst files have not been modified, then the doc parsing does not occur.
If this folder is deleted then it works normally.
A few things that can modify the doc output and are not triggering a new build:

• The python code under _ext
• Changelog fragments

[ewjoachim]

I think this could be solved by implementing the proper callbacks to

app.connect('env-get-updated', get_updated)
# and
app.connect('env-get-outdated', get_outdated)

but the lack of docs on the matter makes it hard to understand exactly what would need to be done in those functions.

(The doc : https://www.sphinx-doc.org/en/master/extdev/appapi.html#events )

Just to make it clear, I understand that this is not a real problem for pylibssh and removing the .doctrees might be enough of a workaround to not spend longer on this problem, I'm mainly doing this to get a better understanding of Sphinx :)

[webknjaz]

@ewjoachim good point! FWIW this is something that should be documented when I start moving things to https://github.com/sphinx-contrib/towncrier.

https://stackoverflow.com/a/44758406/595220 suggests to use -a but that will just rebuild everything every time and so it defeats the whole point of having cached doctrees.
https://www.sphinx-doc.org/en/master/man/sphinx-build.html#description says that specifying positional args will force rebuild but it'll only build those files.

So it looks like if I add two invocations to the tox env, first to build just the changelog document and the second one to rebuild anything else that's changed or new, it may work... But yeah, exploring those events is definitely something that needs to be investigated.