PSA: Changes to |mach doc| generation

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

PSA: Changes to |mach doc| generation

Andrew Halberstadt
I've recently landed some changes to how our docs
are generated in bug 1410424 and bug 1454640:

1. Building subtrees will always work.

Previously if you wanted to run |mach doc <path>|, it
would only work if the <path> happened to have its
own conf.py file. Since not all paths had this, the only
alternative was to build the entire documentation
(which takes a long time).

Now, |mach doc <path>| will work regardless of the
presence of a conf.py.


2. Building subtrees will use the proper configuration.

Similar to 1), running |mach doc <path>| used to use the
conf.py found under <path>. This meant it was using an
entirely different doc configuration than the one that gets
used for publishing to firefox-source-docs.mozilla.org.
This was bad because the docs you were seeing when
testing locally could look vastly different from the ones
that ultimately got published.

Now, we always use tools/docs/conf.py from |mach doc|.
One caveat is that running |mach doc <path>| is now a
bit slower than before (usually an extra ~5 seconds). This
is because our main conf.py file does a bunch of extra
tasks like reading moz.build, generating API docs and
generating a custom index.


3. There is now a livereload server.

This means after the first time you run |mach doc| a
server will be started. Anytime you modify a doc file
under the path you passed in (or any doc file if you
generated the root documentation), a rebuild will
automatically get kicked off and your browser page will
refresh after it's done. Note this doesn't happen instantly.

If you build the root tree (via |mach doc|) and then modify
a file, only the subtree containing that file will be rebuilt.
One known issue with this worfklow is that the original
custom index that |mach doc| generated will be clobbered
and replaced with the index from the rebuilt subtree. I'm
not sure how to fix this :/.

To disable the livereload server, you can run:
$ ./mach doc --no-serve

Let me know if you have any questions or suggestions,
Andrew

_______________________________________________
dev-builds mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-builds
Reply | Threaded
Open this post in threaded view
|

Re: PSA: Changes to |mach doc| generation

Andreas Tolfsen-2
Also sprach Andrew Halberstadt:

> I've recently landed some changes to how our docs
> are generated in bug 1410424 and bug 1454640:
>
> 1. Building subtrees will always work.
> 2. Building subtrees will use the proper configuration.
> 3. There is now a livereload server.

These changes are great and makes it a much more pleasant experience
to write documentation!
_______________________________________________
dev-builds mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-builds