Bug 1484691 - [doc] Don't add doctrees nested under other doctrees to the root index r=nalexander

Currently, it's possible to nest doctrees underneath one another by doing this:

    SPHINX_TREES['foo'] = 'docs'
    SPHINX_TREES['foo/bar'] = 'bar/docs'

(note: the 'bar' doctree doesn't need to be a subdir of foo and can be defined
in a completely separate moz.build)

Doing this means that the docs in 'bar' will be nested underneath the docs in
'foo' when sphinx-build ultimately runs.

This allows us to add 'bar' to foo's index, essentially making bar a subdoc of
foo.  The problem is that we also add bar's docs to the root index here:
https://searchfox.org/mozilla-central/rev/dac799c9f4e9f5f05c1071cba94f2522aa31f7eb/tools/docs/moztreedocs/__init__.py#133

The result is that the main landing page for firefox-source-docs is a big long
list of random unrelated topics. There is no organization or cohesion. By
excluding subdocs from the main index, we can start to move pages around into
some kind of organization that makes sense.

Actually moving those docs will be a lot of work, but at least this will give
us the ability.

Differential Revision: https://phabricator.services.mozilla.com/D16869

--HG--
extra : moz-landing-system : lando

tools/docs/moztreedocs/__init__.py

@@ -130,7 +130,19 @@ class _SphinxManager(object):
         with open(self.index_path, 'rb') as fh:
             data = fh.read()
 
-        indexes = ['%s/index' % p for p in sorted(self.trees.keys())]
+        def is_toplevel(key):
+            """Whether the tree is nested under the toplevel index, or is
+            nested under another tree's index.
+            """
+            for k in self.trees:
+                if k == key:
+                    continue
+                if key.startswith(k):
+                    return False
+            return True
+
+        toplevel_trees = {k: v for k, v in self.trees.items() if is_toplevel(k)}
+        indexes = ['%s/index' % p for p in sorted(toplevel_trees.keys())]
         indexes = '\n   '.join(indexes)
 
         packages = [os.path.basename(p) for p in self.python_package_dirs]