Add Python syntax highlighting to MDN

NEW
Unassigned

Status

P2
enhancement
2 years ago
4 months ago

People

(Reporter: cmills, Unassigned)

Tracking

({in-triage})

Details

(Whiteboard: [specification][type:feature])

What problem would this feature solve?
======================================
We rarely include any Python code on MDN, but recently we've started to include a few articles that feature Python, in our generic beginner's server-side development course. For example:

https://developer.mozilla.org/en-US/docs/Learn/Server-side/Django/Tutorial_local_library_website

The Python syntax highlighting option does not appear to work.

Who has this problem?
=====================
All visitors to MDN

How do you know that the users identified above have this problem?
==================================================================
Because these pages will be viewable by all users.

How are the users identified above solving this problem now?
============================================================
It is not a problem as such. the Python code blocks will just not look quite as nice.

Do you have any suggestions for solving the problem? Please explain in detail.
==============================================================================
Stephanie says we've not included the Python syntax highlighting from the Prism library, so to fix this should be fairly trivial. 

Is there anything else we should know?
======================================
Keywords: in-triage
I'm concerned that this will encourage more Python documentation on MDN, when instead we should be linking to project-specific resources, such as the Django's "Getting Started" guide or the tutorial list on their wiki:

https://docs.djangoproject.com/en/1.10/intro/
https://code.djangoproject.com/wiki/Tutorials
(In reply to John Whitlock [:jwhitlock] from comment #1)
> I'm concerned that this will encourage more Python documentation on MDN,
> when instead we should be linking to project-specific resources, such as the
> Django's "Getting Started" guide or the tutorial list on their wiki:
> 
> https://docs.djangoproject.com/en/1.10/intro/
> https://code.djangoproject.com/wiki/Tutorials

Under normal circumstances, I’d totally agree, yes. But this particular case is an exception. We wanted to include a generic complete beginner’s guide to server-side development in the MDN learning area, because it is an area that people have asked us about covering, and to know the basics of how server-side technologies will benefit budding client-side developers as well.

The aim of this course is not to teach any one particular server-side environment in exhaustive detail — their own communities already do a good job of that — but we can’t really show how such technologies work without showing some actual practical examples. So we are teaching a little bit of Django to demonstrate what we are talking about - chosen due to its incredible popularity and high quality. But we aren't aiming to provide a comprehensive Python or Django course.

Another point in support of adding the Python highlighting to MDN is that many Mozilla tools are written in Python, and we do sometimes have call to document their usage.
This would also be needed for the WebDriver documentation [1], for
which we are currently documenting client examples using a stock
Python client.  We will be providing more code examples in other
language such as Java and C# in the future.

  [1] https://developer.mozilla.org/en-US/docs/Web/WebDriver
This is an easy fix. I'll do up a PR this afternoon.
Assignee: nobody → eshepherd
OK, so the change is easy but unfortunately getting it integrated is not, since it requires doing a bower-installer pass, which is non-trivial. here's the change that needs to be made to the sources:

In settings/common.py, add this line after line 1058:

      "js/libs/prism/prism-pythonjs",

That should be it. Then do the steps needed to run the bower install pass and the other steps to get the changes into place and committed.
Assignee: eshepherd → nobody
The Kuma docs for bower updates are inadequate:

https://kuma.readthedocs.io/en/latest/development.html#front-end-dependencies

Installing git and bower-installer requires root access, which is requires calling docker directly. An improvement would be adding a "make bower-install" command that runs the steps for a developer, replacing steps 2-4:

On the host:
1. Update bower.json.
2. Run "make bower-install".
3. Prepare the dependency to be committed (git add path/to/dependency).

It may be worth updating some of the dependencies (jQuery, etc.) at the same time.
Priority: -- → P2
You need to log in before you can comment on or make changes to this bug.