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 dev-builds@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-builds
