In bug 917988, we just landed support for using Sphinx [1] to manage the build system documentation. You can generate the documentation by running:
$ mach build-docs By default it will generate HTML documentation using the Sphinx MDN theme, so it's Mozilla branded and it is lovely. Sphinx is a pretty powerful tool for documentation. I encourage you to check it out. The docs aren't currently automatically published anywhere. I'll probably throw up a Mozilla Stackato [2] site with them unless someone beats me to it. While this was created to host the build system docs, I know the subject of desiring in-tree documentation has come up before. Political discussions about whether the tree is the best place for a certain piece of documentation aside, I have no problem with non-build groups depositing their docs into this Sphinx project/hierarchy under /build/docs and turning it into a "documentation commons." As long as you don't touch the build system docs or the conf.py file, commit away without review from a build peer. If this takes off, we can establish a /docs directory or we can conjure up a solution that aggregates files from across the tree (so docs live closer to their code). (Currently, I think Sphinx will insist all files be rooted in /build/docs.) Until then, let's see what happens. Finally, please be considerate about the implications of having docs in the tree. Compared to MDN, you lose easier editability, l10n benefits, etc. We in build land plan to use this for lower-level documentation (implementation details, history of decisions, etc). We want this knowledge to live in the tree so it is versioned with the tree and has a better liklihood to stay in sync and be updated as part of patches. We have little to no desire for non-English languages and community editing for these types of docs, so in-tree makes sense for us. YMMV. [1] http://sphinx-doc.org/ [2] https://wiki.mozilla.org/Paas_Apps _______________________________________________ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
