1361729 - Deprecate mdn-sphinx-theme

Status: RESOLVED FIXED

(developer.mozilla.org Graveyard :: General, enhancement, P1)

Description

[John Whitlock [:jwhitlock]]

What feature should be changed? Please provide the URL of the feature if possible.
==================================================================================
The mdn-sphinx-theme is a skin that makes the Kuma documentation look like the MDN documentation:

https://github.com/mdn/sphinx-theme
https://kuma.readthedocs.io/en/latest/
https://pypi.python.org/pypi/mdn-sphinx-theme/2016.0

We should switch to a active, community-supported theme and abandon the mdn-sphinx-theme.


What problems would this solve?
===============================
The mdn-sphinx-theme is often out-of-date with MDN. It has not been updated in 8 months. It is non-trivial to update it [1], and "theme paths" pollute the Kuma base templates, to exclude things like Google Analytics and helpfulness surveys.

Our theme lacks common features of other Sphinx themes, such as documentation search and permanent links to in-page sections (often exposed by a "¶" that appears on hover).  This makes the Kuma documentation less useful than other project's documentation, like Bedrock [2].  We would add these and other features easily by switching to an active, community-supported theme.

Four years ago, one of the design goals of MDN was to collect all the Mozilla documentation into one documentation hub or network (see bug 877197).  The mdn-sphinx-theme was an experiment into what this might look like (bug 877197). However, MDN's documentation style isn't a perfect match for these project's needs (bug 920314). 

In those four years, it is becoming clearer that:
* MDN is best for open web documentation where a community contributes small changes and translations
* Sphinx is a great solution for product documentation maintained by the product team
* ReadTheDocs is the de facto hub for open source project documentation, and should be supported in that role [3].

There may be a place for a Mozilla-default Sphinx theme, but MDN shouldn't be the template.

The current mdn-sphinx-theme loads assets from the MDN CDN, and relies on old versions of assets being kept around indefinitely.  This may change as we move to AWS and serving only the latest version of assets, relying on the external CDN provider to cache assets for a limited amount of time (1-12 months).  The theme would need to be updated to include the assets in the package, which will require some development effort, and would make a bulky, non-optimized theme.

[1] https://kuma.readthedocs.io/en/latest/documentation.html#regenerate-the-mdn-sphinx-theme-template
[2] http://bedrock.readthedocs.io/en/latest/
[3] http://blog.readthedocs.com/rtd-awarded-mozilla-open-source-support-grant/


Who would use this?
===================
Kuma would stop using mdn-sphinx-theme.

There are a handful of other projects that continue to use the theme [4], but most appear to not have been updated in a few years, and continue to use old releases.  If these projects are still maintained, they can switch to a community-supported Sphinx theme.

[4] https://github.com/search?o=desc&q=mdn-sphinx-theme&s=indexed&type=Code&utf8=✓

What would users see?
=====================
Kuma documentation users would see docs that look more like other open-source documentation, and have all the features like search and permalink that they expect.

What would users do? What would happen as a result?
===================================================
Users would continue using docs.

Kuma would drop Sphinx-generation code paths in the code and templates, making our base templates easier to understand and upgrade.

Project owners wouldn't waste time considering mdn-sphinx-theme

Is there anything else we should know?
======================================
Documentation is hard. People don't read. If your project documentation doesn't make a lot of sense, then you need to work on your developer interfaces.

Comment 1

[John Whitlock [:jwhitlock]]

As predicted, the move to AWS (bug 1110799) has broken the theme. We're moving to the Alabaster theme: mozilla/kuma#4457 .

Comment 2

[[github robot]]

Commits pushed to master at https://github.com/mozilla/kuma

https://github.com/mozilla/kuma/commit/0b5e20e9a30b6d2dbcd489d786d1f6012056f1ef
bug 1361729: Switch to alabaster theme

https://github.com/mozilla/kuma/commit/0e84815bc629f9244e5139bc56a1c43794e4adcc
bug 1361729: Update links

https://github.com/mozilla/kuma/commit/51a83758abe4ff4b7365ab6d179759ba1f89c4ef
Merge pull request #4457 from mozilla/alabaster-1361729

bug 1361729: Switch to alabaster theme

Comment 3

[John Whitlock [:jwhitlock]]

Added a deprecation warning to https://github.com/mdn/sphinx-theme

Comment 4

[[github robot]]

Commits pushed to master at https://github.com/mozilla/kuma

https://github.com/mozilla/kuma/commit/14521cb18ad486575b8aeb1459ecb03a3ff6e9dc
bug 1361729: Remove mdn-sphinx-template support

* Remove "is_sphinx" tests from base template
* Remove sphinx.css generation
* Remove URLAbsolutionFilter from content filters
* Remove ./manage.py generate_sphinx_template

https://github.com/mozilla/kuma/commit/2798109be25ef83c70a47402e65e504282ddee58
Merge pull request #4487 from jwhitlock/remove-sphinx-template-1361729

bug 1361729: Remove mdn-sphinx-template support