Closed Bug 1410424 Opened 7 years ago Closed 6 years ago

Provide a 'live' preview when editing in-tree docs

Categories

(Developer Infrastructure :: Source Documentation, enhancement)

enhancement
Not set
normal

Tracking

(firefox61 fixed)

RESOLVED FIXED
mozilla61
Tracking Status
firefox61 --- fixed

People

(Reporter: ahal, Assigned: ahal)

References

Details

Attachments

(3 files)

We should aim to provide some kind of live preview when editing. One approach might be to use:
https://github.com/GaretJax/sphinx-autobuild

I haven't tried it, but from the looks of it sphinx-autobuild will let us spin up a local webserver that will detect when a source file is changed and automatically rebuild the html in the background. Depending how long this rebuild takes, it wouldn't quite be "live", but would be a lot better than the current scenario.

Another simpler option might be to hook up:
https://github.com/anru/rsted

Looks like there's a fork that supports sphinx specific markup too:
http://livesphinx.herokuapp.com/
We detect watchman in configure now. It is trivial to configure watchman to launch a process when watched files are changed.

The tricky part is unregistering the watchman state when we no longer care about it. If you have a process running in the foreground, that's much easier :)
See Also: → 1415673
Product: Core → Firefox Build System
I stumbled across python-livereload:
https://github.com/lepture/python-livereload

I was able to get a working prototype up pretty quickly (will upload soon). To try it out just run:

  $ mach doc tools/lint

This will build and serve the docs. Any files modified under the specified path will cause a rebuild and refresh of the browser. There are a couple of caveats:

1) I haven't been able to figure out how to watch all doc dirs when building the root of the doc tree (besides parsing SPHINX_TREES out of moz.build a second time).

2) I had to remove the ability to run multiple paths with |mach doc| (to avoid the need to spin up multiple servers in multiple threads). I don't think this feature was all that useful to begin with though.

But even still, this looks like it could be very useful!
Assignee: nobody → ahalberstadt
Status: NEW → ASSIGNED
I started going down a bit of a rabbit hole which is turning into a major overhaul of the doc generation process. I think the commits I've posted so far are a good improvement on the status quo, so I'm going to try and get them landed first and file a follow-up for some of the other stuff I've changed.

For the curious, the root of that rabbit hole was making all |mach doc| invocations use tools/docs/conf.py, which means always building with the mozbuild.sphinx extension. Then how do you make that more performant, generate toctrees properly and play nicely with livereload, etc. This is more of a side-project I've started in my spare time, so it might be awhile until I get it working nicely.
Component: General → Generated Documentation
Blocks: 1454640
Comment on attachment 8965713 [details]
Bug 1410424 - [docs] Remove ability to specify multiple doc paths at the same time

https://reviewboard.mozilla.org/r/234574/#review243024


Code analysis found 1 defect in this patch:
 - 1 defect found by mozlint

You can run this analysis locally with:
 - `./mach lint path/to/file` (JS/Python)


If you see a problem in this automated review, please report it here: http://bit.ly/2y9N9Vx


::: tools/docs/mach_commands.py:62
(Diff revision 2)
>          import sphinx
>          import webbrowser
>          import moztreedocs
>  
> -        if not outdir:
> -            outdir = os.path.join(self.topobjdir, 'docs')
> +        outdir = outdir or os.path.join(self.topobjdir, 'docs')
> +        format_outdir = os.path.join(outdir, fmt)

Error: Undefined name 'fmt' [flake8: F821]
Comment on attachment 8965551 [details]
Bug 1410424 - [mozbuild] Add a 'quiet' argument to VirtualenvManager.install_pip_requirements

https://reviewboard.mozilla.org/r/234338/#review243982
Attachment #8965551 - Flags: review+
Comment on attachment 8965713 [details]
Bug 1410424 - [docs] Remove ability to specify multiple doc paths at the same time

https://reviewboard.mozilla.org/r/234574/#review243984
Attachment #8965713 - Flags: review+
Attachment #8965551 - Flags: review?(core-build-config-reviews)
Attachment #8965713 - Flags: review?(core-build-config-reviews)
Comment on attachment 8965714 [details]
Bug 1410424 - [docs] Support live reloading with |mach doc|

https://reviewboard.mozilla.org/r/234576/#review243994

The live reloading is nice! I think it would be great if this worked for other directories as well, but it sounds like you'll handle that in a followup.
Attachment #8965714 - Flags: review+
Attachment #8965714 - Flags: review?(core-build-config-reviews)
Yeah, bug 1454640 will fix a lot of general problems with the doc generation.
Pushed by ahalberstadt@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/1b366ada7c5d
[mozbuild] Add a 'quiet' argument to VirtualenvManager.install_pip_requirements r=mshal
https://hg.mozilla.org/integration/autoland/rev/15a5e48d01a5
[docs] Remove ability to specify multiple doc paths at the same time r=mshal
https://hg.mozilla.org/integration/autoland/rev/d34cf7a17b3b
[docs] Support live reloading with |mach doc| r=mshal
https://hg.mozilla.org/mozilla-central/rev/1b366ada7c5d
https://hg.mozilla.org/mozilla-central/rev/15a5e48d01a5
https://hg.mozilla.org/mozilla-central/rev/d34cf7a17b3b
Status: ASSIGNED → RESOLVED
Closed: 6 years ago
Resolution: --- → FIXED
Target Milestone: --- → mozilla61
Product: Firefox Build System → Developer Infrastructure
You need to log in before you can comment on or make changes to this bug.