Bug 1484691 - [doc] Don't add doctrees nested under other doctrees to the root index r=nalexander
authorAndrew Halberstadt <ahalberstadt@mozilla.com>
Fri, 18 Jan 2019 20:10:18 +0000
changeset 514472 19b949191e5c
parent 514471 24e1359b53ca
child 514473 1e0f41f31abe
push id1953
push userffxbld-merge
push dateMon, 11 Mar 2019 12:10:20 +0000
treeherdermozilla-release@9c35dcbaa899 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersnalexander
bugs1484691
milestone66.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
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
tools/docs/moztreedocs/__init__.py
--- a/tools/docs/moztreedocs/__init__.py
+++ b/tools/docs/moztreedocs/__init__.py
@@ -125,17 +125,29 @@ class _SphinxManager(object):
 
         copier = FileCopier()
         m.populate_registry(copier)
         copier.copy(self.staging_dir)
 
         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]
         packages = ['python/%s' % p for p in packages]
         packages = '\n   '.join(sorted(packages))
         data = data.format(indexes=indexes, python_packages=packages)
 
         with open(os.path.join(self.staging_dir, 'index.rst'), 'wb') as fh: