877197 - Support reST documentation published with Sphinx / ReadTheDocs

Status: RESOLVED WONTFIX

(developer.mozilla.org Graveyard :: General, defect, P2)

Description

[Les Orchard [:lorchard]]

Many Mozilla-related docs are written using reStructuredText, and published as HTML on readthedocs.org:

    https://readthedocs.org/search/project/?q=mozilla

641 results - that suggests a corpus of doco that I really wish was better represented in MDN.

This should be somehow connected to/from MDN, and uses ReadTheDocs.org:

    http://firefox-marketplace-api.readthedocs.org/en/latest/

That uses a Mozilla Sandstone theme for Sphinx:

    https://github.com/ametaireau/mozilla-sphinx-theme

In bug 873256, I made a proof-of-concept theme for RTD/Sphinx. It shares the MDN design and has top-level nav pointing back to MDN.

It might also be interesting to somehow include RTD docs in our search indexing.

And, to make this even more official, we can look into using a developer.mozilla.org domain for docs on RTD

Comment 1

[Les Orchard [:lorchard]]

Also, relevant, with regard to my PoC MDN Sphinx theme for bug 873256: I've very hastily hacked together a Sphinx theme based on MDN and used it to build docs for one of my Django projects.

If you want to see how the transition from MDN to RtD looks, try clicking on the "Check out this doc" link on my User page:

    https://developer.mozilla.org/en-US/docs/User:lmorchard

That link should lead to docs for one of my Django apps, here:

    https://django-valet-keys.readthedocs.org/en/latest/

The theme still needs refinement, and will need a complete overhaul whenever we have a redesign. But, it didn't take much work to get it into its current state. Devil's in the details, of course.