950945 - Update the docs theme to look like the new MDN

Status: RESOLVED FIXED

(developer.mozilla.org Graveyard :: Design, defect)

Description

[Matt Basta [:basta]]

The new MDN is out, but our docs still look like the old MDN. We should upgrade if possible.

Comment 1

[Andy McKay]

We'll need to get a new build of mdn-sphinx-theme out with the new look and feel. Les, did you have a script to generate most of that?

Comment 3

[David Walsh :davidwalsh]

FWIW, there's a `generate_sphinx_template` command within kuma to generate the new theme HTML.

Comment 4

[Les Orchard [:lorchard]]

(In reply to David Walsh :davidwalsh from comment #3)
> FWIW, there's a `generate_sphinx_template` command within kuma to generate
> the new theme HTML.

Generating a theme update with this command is currently broken, need to investigate. Looks like we've got some things in the base template that are dependent on access to a real request, which we don't have when we're trying to generate a theme

Comment 5

[Andy McKay]

Just to let you know, the old mdndev theme no longer works because I think a few MDN assets got moved, so we've turned it off on our docs.

Comment 6

[Les Orchard [:lorchard]]

Fixed the errors, generated a new theme layout, uploaded to pypi:

https://pypi.python.org/pypi/mdn-sphinx-theme/0.5

But, some things may still be broken because we haven't really checked out how the theme works now with the new design

Comment 7

[[github robot]]

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

https://github.com/mozilla/kuma/commit/ba2b9f5285c63608ab337db5b2a62cb6f8e12e37
bug 950945: Fix an error with waffle while attempting to generate sphinx theme layout

https://github.com/mozilla/kuma/commit/c82d5507c7c62e21fb3fbd875c1a50fdbbf34c5d
Merge pull request #2209 from lmorchard/fix-sphinx-theme-generation

bug 950945: Fix an error with waffle while attempting to generate sphinx theme layout

Comment 8

[Gregory Szorc [:gps]]

I tried out 0.5 and the styling is off. Things like definition lists appear as a bunch of narrowly-padded paragraphs. I didn't debug it because it looks obviously wrong. I suspect anyone who throws an existing Sphinx documentation tree at 0.5 will notice immediately.

Comment 9

[Gregory Szorc [:gps]]

Any update on this? The docs in mozilla-central have been busted for a few months now. People keep asking me why the docs are broken :/

https://ci.mozilla.org/job/mozilla-central-docs/Tree_Documentation/index.html

Comment 10

[Luke Crouch [:groovecoder]]

You can try to update the theme as per :lorchard's Comment 6:

https://bugzilla.mozilla.org/show_bug.cgi?id=950945#c6

If that doesn't work for you, it will be faster to revert the docs to another theme until we can update this sphinx theme.

Comment 11

[MDN Team (:mdn-dev)]

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

https://github.com/mozilla/kuma/commit/6b7252305561b137c80c92908b4b91efe05673d2
bug 950945: Fix generate_sphinx_template

Fix errors when running ./manage.py generate_sphinx_template to generate
the Sphinx template for the MDN theme at:

https://github.com/mdn/sphinx-theme

In addition, fix some issues in the template:

* Single-escape the title rather than double-escape
* Copyright always covers current year
* Add an empty <div class="page-buttons"> so wiki.js runs successfully
* Add class="text-content" so documentation content is styled correctly
* IE shims for old versions have the correct path

https://github.com/mozilla/kuma/commit/22ed90b7e069cc7a0de377a0b5e591b4293229cf
bug 950945: Adjust README.rst for dev docs

Omit the badges from the documentation, and preserve linebreaks in the
quick links table.

https://github.com/mozilla/kuma/commit/83634efc0d9d8f1ceba989929c39648460390830
bug 950945: Omit social graph, etc. from Sphinx

Omit social tags, search nav, and Google Analytics initialization in the
MDN Sphinx template.

https://github.com/mozilla/kuma/commit/1d9b5453556183908d6210e5ace2c384b573779a
bug 950945: Document the documentation

https://github.com/mozilla/kuma/commit/b80758cecb629ab0a90f1e613b3771528f2e3565
bug 950945: Sync Jinja2 versions

Sync the version of Jinja2 in docs.txt with default.txt.

docs.txt contains the requirements for building the documentation, which
is normally not done in the development environment, but having the same
versions will mean that it is safe to install them alongside other
development requirements.

https://github.com/mozilla/kuma/commit/8e761c7e664641da7945055677150167619aaa5c
bug 950945: Clarify where to build docs

Documentation can be built in the VM, or experienced Python developers can
create a new virtualenv to install the requirements and build the
documentation, in a similar way to ReadTheDocs.

https://github.com/mozilla/kuma/commit/d200a02c302edb4dd9b5855d81e3ecaafcee110d
bug 950945: Set LANG for Sphinx template

https://github.com/mozilla/kuma/commit/46e55b90bc9c3c9560119874d779aaae37bfcad6
bug 950945: Add <!DOCTYPE> to Sphinx Template

The <!DOCTYPE> tag is in the Jinja2 rendered output, but is not parsed
as a token by html5lib. The html5lib docs imply that the "dom"
treebuilder might parse this, but the default "etree" one does not. In
any case, add it as the first element.

https://github.com/mozilla/kuma/commit/609f6e527c035410e3eab9de36411b66394a0213
Merge pull request #3954 from mozilla/sphinx_template_950945

Bug 950945: Fix and improve MDN Sphinx template

Comment 12

[MDN Team (:mdn-dev)]

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

https://github.com/mozilla/kuma/commit/597b3126d430a900edc964c7313e40e91f4b7b17
bug 950945: Update mdn-sphinx-theme to 2016.0

https://github.com/mozilla/kuma/commit/44776ad9aa8d1d72847899c9ba4b2ba6ff89b25d
Merge pull request #3966 from mozilla/update_2016.0_950945

bug 950945: Update mdn-sphinx-theme to 2016.0

Comment 13

[John Whitlock [:jwhitlock]]

mdn-sphinx-theme==2016.0 [1] doesn't include the broken links, so marking this as fixed.  However, we're abandoning the theme (bug 1361729), so I don't advise using it going forward, unless you want to take on ownership of the theme.

[1] https://pypi.python.org/pypi/mdn-sphinx-theme/2016.0
[2] https://github.com/mdn/sphinx-theme