Run sphinx-autobuild via tox -e docs-live[-src]

[rmartin16]

Changes

• Adds support to run sphinx-autobuild from tox
• Running tox -e docs-live will incrementally build any detected changes within the docs directory
• Running tox -e docs-live-src will include rebuilding for changes to docstrings in the source that are compiled in to the documentation....but this requires a full rebuild of the docs for any changes since Sphinx doesn't have a mapping of source files to docs files.

PR Checklist:

• All new features have been tested
• All new features have been documented
• I have read the CONTRIBUTING.md file
• I will abide by the code of conduct

[rmartin16]

Do the docs use docstrings from elsewhere than core/src/toga/?

[HalfWhitt]

Oh hell yes. One further idea / request: it looks like there's also an --open-browser flag, so you don't even have to manually copy the local address to your browser. Any objection to including that too?

[HalfWhitt]

In my usage so far, this seems confusingly inconsistent. It always registers a file save in the console, but sometimes the changes are updated in the browser and sometimes they aren't. I haven't yet been able to determine a rhyme or reason to it.

[freakboy3742]

Do the docs use docstrings from elsewhere than core/src/toga/?

No - the public docs should only be dependent on the toga-core package.

Oh hell yes. One further idea / request: it looks like there's also an --open-browser flag, so you don't even have to manually copy the local address to your browser. Any objection to including that too?

That seems like reasonable thing to turn on. Alternatively (or as well), you could configure the tox target so that it allows passthrough of command line arguments (see how the tox -e py target is configured) so that tox -e docs-live -- --open-browser would be legal. I'll leave it up to you @rmartin16 to make a call on which one feels better as a user.

[rmartin16]

After experimenting with --open-browser, I'm definitely hesitant to invoke it by default. Initially, just adding --open-browser in tox caused it to open the docs in Lynx...which is a fun way to browse web pages (although stdin was getting mangled somehow so it didn't even work). I eventually intuited that the webbrowser module must not think I have X running....so, I passed through the DISPLAY environment variable and got a error saying Firefox basically wasn't cooperating and the page cannot be opened. On Windows, the experience went better and Edge opened.

So, I'm inclined to leave the eccentricities of webbrowser out while allowing anyone to use it via positional arguments at the command line. Furthermore, the hyperlink shown after the docs are built should be control-clickable in any competent terminal.

I also added --port 0 to avoid port conflicts since 8000 is the default and a popular one at that.

[rmartin16]

Scratch the random port; it's too annoying if you restart autobuild and expect the previous browser tab you were using to work again.

As for the inconsistencies you noted, @HalfWhitt, I've been seeing some bizarre things as well. Lacking intimate knowledge of how Sphinx works....my assumption is the reuse of the _build/html directory is leading to a strange mix of new and outdated pages somehow.

[rmartin16]

I decided to re-work all of this from my original implementation.

Using -E, -a, and -d {envtmpdir}/doctrees all the time makes all of this really slow since Sphinx basically needs to start from scratch every time. In your local environment, though, using all the caching really speeds things up. Use tox -e docs -- -aE if you want to start from scratch locally; tox -e docs-all will continue always re-reading everything, though.

Using -v in a terminal creates a worse experience since it needlessly lists all the files being read instead of using the screen redrawing to list the files being processed.

[HalfWhitt]

I wonder if the inconsistent loading has anything to do with the fact that tox doesn't seem to be installing core as editable; that's probably why deleting the relevant environment folder in .tox always updates docstrings, since the packages are all reinstalled from their current state.

EDIT: Eh, never mind. Changing that doesn't seem to make it any more reliable.

[rmartin16]

I wonder if the inconsistent loading has anything to do with the fact that tox doesn't seem to be installing core as editable; that's probably why deleting the relevant environment folder in .tox always updates docstrings, since the packages are all reinstalled from their current state.

Actually, that's a good point; I think all my testing of seeing edits in the "live view" was while running the command without tox so I could get the right command line.

That's why the usual recommendation for updating API docstrings in your local build was to run tox -re docs-all...which is the equivalent of deleting the .tox directory but a little cleaner.

At any rate, I'll have it install an editable version....that should be fine since its essentially what's happening when I run sphinx directly in the command line.

[rmartin16]

EDIT: Eh, never mind. Changing that doesn't seem to make it any more reliable.

As for other inconsistencies, some examples may help since using a different build directory seemed to make everything a lot better for me.

[rmartin16]

I also realized the docs-live-src tox env needed the -E/--fresh-env flag so it didn't re-use the cached docstrings.

[rmartin16]

FYI; beware of using {/} as a trailing path separator; it doesn't work that well on Windows right now.

• On Windows, trailing path sep causes command quoting issues tox-dev/tox#3222

[freakboy3742]

Huge +1 on this. I've added a reference to the contribution guide so that everyone knows this exists.

[HalfWhitt]

Thank you so much for implementing this rmartin16, you rock! The merged version is working beautifully.