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)
Developer Infrastructure
Source Documentation
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/
Comment 1•7 years ago
|
||
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 :)
Updated•6 years ago
|
Product: Core → Firefox Build System
Assignee | ||
Comment 2•6 years ago
|
||
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!
Comment hidden (mozreview-request) |
Assignee | ||
Updated•6 years ago
|
Assignee: nobody → ahalberstadt
Status: NEW → ASSIGNED
Comment hidden (mozreview-request) |
Comment hidden (mozreview-request) |
Comment hidden (mozreview-request) |
Assignee | ||
Comment 7•6 years ago
|
||
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.
Assignee | ||
Updated•6 years ago
|
Component: General → Generated Documentation
Comment hidden (mozreview-request) |
Comment hidden (mozreview-request) |
Comment hidden (mozreview-request) |
Comment 11•6 years ago
|
||
mozreview-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/#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 hidden (mozreview-request) |
Comment hidden (mozreview-request) |
Comment 14•6 years ago
|
||
mozreview-review |
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 15•6 years ago
|
||
mozreview-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+
Updated•6 years ago
|
Attachment #8965551 -
Flags: review?(core-build-config-reviews)
Updated•6 years ago
|
Attachment #8965713 -
Flags: review?(core-build-config-reviews)
Comment 16•6 years ago
|
||
mozreview-review |
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+
Updated•6 years ago
|
Attachment #8965714 -
Flags: review?(core-build-config-reviews)
Assignee | ||
Comment 17•6 years ago
|
||
Yeah, bug 1454640 will fix a lot of general problems with the doc generation.
Comment 18•6 years ago
|
||
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
Comment 19•6 years ago
|
||
bugherder |
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
status-firefox61:
--- → fixed
Resolution: --- → FIXED
Target Milestone: --- → mozilla61
Updated•2 years ago
|
Product: Firefox Build System → Developer Infrastructure
You need to log in
before you can comment on or make changes to this bug.
Description
•