<div dir="ltr">Documentation is hard. It's difficult to write, difficult to find and always out<br>of date. That's why we implemented our in-tree documentation system that<br>underpins <a href="http://firefox-source-docs.mozilla.org">firefox-source-docs.mozilla.org</a>. The documentation lives next to the<br>code that it documents, so it can be updated within the same commit that makes<br>the underlying changes. Unfortunately, this system has never been a pleasure to<br>work with. Docs are slow to build, RST is foreign to most and the moz.build<br>syntax to integrate them is confusing. Not to mention some serious bugs around<br>how files are uploaded and stored in S3.<br><br>I'm happy to announce many great new features for firefox-source-docs, courtesy<br>of our GSoC student Shivam (aka :championshuttler). You can see a blog post he<br>wrote on his experience <a href="https://medium.com/@shivams2799/adventures-in-gsoc-649434368314">here</a>. Below is a list of all the work and awesome new<br><div>features he added to our documentation infrastructure. Please note that <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1576912">bug 1576912</a> <br></div><div>tracks saving this information into the docs themselves.</div><br><br><b>Server Synchronization</b><br><br>Previously, the doc system had a surprisingly major flaw. Docs were only ever<br>uploaded to S3, never deleted. This meant that even if a source file no longer<br>exists (e.g it was removed or renamed), the related page would continue to live<br><div>on the server indefinitely. External links to the page would continue to function,</div><div>the users of the link being none-the-wiser. Yikes!</div><br>We now compare all the files that exist on the server against the list of source<br>files in `mozilla-central`. Any files on the server that no longer exist in<br>`mozilla-central` are removed.<br><br><br><b>Redirects</b><br><br>We now have the ability to define redirects in-tree! This will allow us to<br>refactor and move docs around to our hearts content without needing to worry<br>about stale external URLs. To set up a redirect simply add a line to this file:<br><br><a href="https://searchfox.org/mozilla-central/source/tools/docs/redirects.yml">https://searchfox.org/mozilla-central/source/tools/docs/redirects.yml</a><br><br>Any request starting with the prefix on the left, will be rewritten to the<br>prefix on the right by the server. So for example a request to<br>`/testing/marionette/marionette/index.html` will be re-written to<br>`/testing/marionette/index.html`. Amazon's API only supports prefix redirects,<br>so anything more complex isn't supported.<br><br><br><b>Nested Doc Trees</b><br><br>This has been implemented for awhile and wasn't part of the GSoC project, but<br>due to a lack of redirects it didn't make sense to advertise too broadly. Up<br>until recently, we've tended to add all doc folders to the root index. In other<br><div>words each subsection is visible at the top level, creating a rather <a href="https://firefox-source-docs.mozilla.org/">long and</a></div><div><a href="https://firefox-source-docs.mozilla.org/">incoherent</a> list of pages to the left.</div><br>This feature essentially means we can now group related docs together under<br>common "landing pages". This will allow us to refactor the docs into a structure<br>that makes more sense. For example we could have a landing page for docs<br>describing Gecko's internals, and another one for docs describing developer<br>workflows in `mozilla-central`.<br><br>Mark Banner has already started to organize some of the docs under some of these<br>landing pages. See <a href="https://hg.mozilla.org/mozilla-central/rev/f0eedecf8f2d">this commit</a> for a rough example.<br><br>To clarify a few things:<br><br>1. The path specified in `SPHINX_TREES` <i>does not</i> need to correspond to a path<br>in `mozilla-central`. For example, I could register my docs using<br>`SPHINX_TREES["/foo"] = "docs"`, which would make that doc tree accessible at<br>`<a href="http://firefox-source-docs.mozilla.org/foo`">firefox-source-docs.mozilla.org/foo`</a>.<br><br>2. Any subtrees that are nested under another index will automatically be hidden<br>from the main index.  This means you should make sure to link to any subtrees<br>from somewhere in the landing page. So given my earlier doc tree at `/foo`, if I<br>now created a subtree and registered it using `SPHINX_TREES["/foo/bar"] =<br>"docs"`, those docs would <i>not</i> show up in the main index.<br><br>3. The relation between subtrees and their parents does not necessarily have any<br>bearing with their relation on the file system. For example, a doc tree that<br>lives under `/devtools` can be nested under an index that lives under<br>`/browser`.<br><br>I realize this explanation is about as clear as mud, so feel free to reach out<br>to me if you need a hand. Also keep an eye on <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1576912">bug 1576912</a> which will provide a<br>better explanation of how registration works.<br><br><br><b>ReStructuredText Linter</b><br><br><div>RST isn't the easiest of markup languages, but it's powerful and  what `Sphinx`</div><div>(the library used to build our docs) uses, so we're stuck with it. But at least we</div><div>now have a linter which will catch basic problems in `.rst` files early. Be sure to</div><div>run `./mach lint -o` to test your outgoing changes before submitting to review!<br></div><br><br><b>Mermaid Integration</b><br><br><div><a href="https://mermaidjs.github.io/#/">Mermaid</a> is a tool that lets you generate flow charts, sequence diagrams, gantt</div><div>charts, class diagrams and vcs graphs from a simple markup language. This<br></div><div>means you can embed these directly in the source rather than creating an image<br></div>with some external tool and then checking it into the tree. To add a diagram,<br>simply put something like this into your page:<br><br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">.. mermaid::<br><br>    graph TD;<br>        A-->B;<br>        A-->C;<br>        B-->D;<br>        C-->D;<br></blockquote><br>See mermaid's <a href="https://mermaidjs.github.io/#/">official docs</a> for more details on the syntax.<br><br><br><b>Performance, Warnings and Lint Issues</b><br><br>Shivam also made many smaller changes, including modest perf improvements to the<br>build, fixing some of the warnings generated from `Sphinx` and enabling the `rst` linter<br>across the tree by fixing (almost) all pre-existing issues.<br><br><br><b>Final Words</b><br><br>Our in-tree documentation could be <i>a lot</i> better than it currently is. If you<br>are interested in helping to re-organize and improve them, please reach out<br><div>(especially if you have technical writing skills)! We now have many of the tools that</div><div>we were previously lacking.<br></div><br>I'd also like to thank Shivam for all the great work he put into this project!<br><br>As always, let me know if you have any questions or concerns.<br>Cheers,<br>Andrew<br></div>