Closed Bug 1484691 Opened 6 years ago Closed 5 years ago

Implement ability to nest SPHINX_TREES

Categories

(Developer Infrastructure :: Source Documentation, enhancement)

enhancement
Not set
normal

Tracking

(firefox66 fixed)

RESOLVED FIXED
mozilla66
Tracking Status
firefox66 --- fixed

People

(Reporter: ahal, Assigned: ahal)

References

(Blocks 1 open bug)

Details

Attachments

(1 file)

Our in-tree documentation is very flat, every entry in SPHINX_TREES is added to the root toctree:
https://firefox-source-docs.mozilla.org/

This leads to a long list of random and in-cohesive pages that don't have anything to do with one another. If we want firefox-source-docs to supplant MDN, we need the ability to organize all these different sections by category that have their own landing page (like we have on MDN).

The root toctree should only have a handful of top-level categories (things like "Firefox", "Build", "Developer Workflow", "Localization", etc). Each category should have something of a landing page that explains what it contains and links to the subsections within.

I haven't looked into how we might implement this, but a very very rough idea might be do something like this:

/testing/moz.build:
SPHINX_TREES['automated_testing'] = 'docs'

/testing/mochitest/moz.build:
SPHINX_TREES.automated_testing['mochitest'] = 'docs'

This would put /testing/docs under the root toctree, and nest /testing/mochitest/docs under the "Automated Testing" category's toctree.
Blocks: 1513821

Looked into this a little. I don't think we need to change SPHINX_TREES at all. In the previous example, we can use:

/testing/moz.build:
SPHINX_TREES['automated_testing'] = 'docs'

/testing/mochitest/moz.build
SPHINX_TREES['automated_testing/mochitest'] = 'docs'

This will copy the mochitest docs under the automated_testing ones which is what we want. However, currently this still puts the mochitest docs at the toplevel toctree. The reason for this is that for every SPHINX_TREES definition we just stuff the path to its index.rst directly into the root index, no matter where the sub-index happens to live:
https://searchfox.org/mozilla-central/source/tools/docs/moztreedocs/__init__.py#133

So to get a doc dir nested under another, we only need to do two things:

  1. Filter out self.trees in the above link such that only top-level doc dirs are added to the root index
  2. Manually link to the subdir from the parent dir (either by adding it to the toctree, or using links or whatever)

Requirement 2 is out of scope of this bug. While it might be nice to have some automatic way of inserting the subdocs into the parent's toctree, it isn't strictly necessary (and in fact, we may want to avoid doing this in some cases).

That means, the only thing necessary to fix this should be a fairly minor patch! Then we can start to think about re-organizing our docs (and all of the pitfalls like URL redirection that will come out of that).

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.

Assignee: nobody → ahal
Status: NEW → ASSIGNED
Pushed by ahalberstadt@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/19b949191e5c
[doc] Don't add doctrees nested under other doctrees to the root index r=nalexander
Status: ASSIGNED → RESOLVED
Closed: 5 years ago
Resolution: --- → FIXED
Target Milestone: --- → mozilla66
Product: Firefox Build System → Developer Infrastructure
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Created:
Updated:
Size: