wbamberg

JavaScript reference docs structure specification

This document describes the structure we want to require for JavaScript reference documentation.

Recipes and ingredients overview

It is expected that pages documenting different sorts of thing will need to contain different elements. For example, the page for the JavaScript BigInt class will want to contain lists of links to its members, while the page for the JavaScript BigInt.asUintN() static method will want to contain a section describing the method syntax.

To reflect this, a "recipe" is a short YAML file that describes at a high level the elements that a particular type of page is expected to have. A recipe provides a list of elements, that are expected to appear in the page in the order given. So for each distinct type of page, we define a single recipe.

For each page:

Find the target interface(s) for the event. This should be listed in the event's page. For example, https://developer.mozilla.org/en-US/docs/Web/Events/drag lists Document, Element as the targets.
Move the page under the target interface, with the name "eventname_event". For example: https://developer.mozilla.org/en-US/docs/Web/API/Document/drag_event. Update the page as described in "Event page updates" below, and update the main interface page as described in "Interface page updates" below.
Check for translations of the event page (do this by hovering over the "Languages" item in the header). If the page has translations, move them as well (but don't bother updating the pages at all).
If the original page listed multiple targets (e.g. https://developer.mozilla.org/en-US/docs/Web/Events/drag lists Document and Element as the targets), then you will need to do the above process multiple times, except that the second time,

	"use strict";

	function toBinary(string) {
	const codeUnits = new Uint16Array(string.length);
	for (let i = 0; i < codeUnits.length; i++) {
	codeUnits[i] = string.charCodeAt(i);
	}
	return String.fromCharCode(...new Uint8Array(codeUnits.buffer));
	}

	* Learn HTML
	* Introduction
	[chapters]
	* Multimedia and embedding
	[chapters]
	* Forms
	[chapters]
	* Tables
	[chapters]
	* Reference

	{
	"html": {
	"elements": {
	"aside": {
	"title": "<aside>: The Aside element",
	"mdn_url": "https://developer.mozilla.org/docs/Web/HTML/Element/aside",
	"interactive-example": "https://interactive-examples.mdn.mozilla.net/pages/tabbed/aside.html",//optional
	"browser-compatibility": {//bcd_for_html.elements.aside},
	"examples": [
	{

	Attaching to kuma_kumascript_1
	kumascript_1 \| internal/modules/cjs/loader.js:583
	kumascript_1 \| throw err;
	kumascript_1 \| ^
	kumascript_1 \|
	kumascript_1 \| Error: Cannot find module 'winston'
	kumascript_1 \| at Function.Module._resolveFilename (internal/modules/cjs/loader.js:581:15)
	kumascript_1 \| at Function.Module._load (internal/modules/cjs/loader.js:507:25)
	kumascript_1 \| at Module.require (internal/modules/cjs/loader.js:637:17)
	kumascript_1 \| at require (internal/modules/cjs/helpers.js:22:18)

	Name Command State Ports
	--------------------------------------------------------------------------------
	kuma_api_1 gunicorn -w 4 --bind Up 0.0.0.0:8001->8000/tcp
	0.0.0 ...
	kuma_elasticsearch_1 /bin/bash bin/es-docker Up 9200/tcp, 9300/tcp
	kuma_kumascript_1 node run.js Exit 1
	kuma_memcached_1 docker-entrypoint.sh Up 11211/tcp
	memcached
	kuma_mysql_1 docker-entrypoint.sh Up 3306/tcp
	mysql ...

	./svg/attributes/xlink.json: "description": "<code>xlink:actuate</code>",
	./svg/attributes/xlink.json: "description": "<code>xlink:arcrole</code>",
	./svg/attributes/xlink.json: "description": "<code>xlink:role</code>",
	./svg/attributes/xlink.json: "description": "<code>xlink:show</code>",
	./svg/attributes/xlink.json: "description": "<code>xlink:title</code>",
	./svg/attributes/xlink.json: "description": "<code>xlink:type</code>",
	./svg/attributes/style.json: "description": "Animation support",
	./svg/attributes/core.json: "description": "xml:base",
	./svg/attributes/core.json: "description": "xml:lang",
	./svg/attributes/core.json: "description": "xml:space",

	$ docker-compose exec web ./manage.py migrate
	System check identified some issues:

	WARNINGS:
	?: (django_mysql.W001) MySQL Strict Mode is not set for database connection 'default'
	HINT: MySQL's Strict Mode fixes many data integrity problems in MySQL, such as data truncation upon insertion, by escalating warnings into errors. It is strongly recommended you activate it. See: https://django-mysql.readthedocs.io/en/latest/checks.html#django-mysql-w001-strict-mode
	?: (mysql.W002) MySQL Strict Mode is not set for database connection 'default'
	HINT: MySQL's Strict Mode fixes many data integrity problems in MySQL, such as data truncation upon insertion, by escalating warnings into errors. It is strongly recommended you activate it. See: https://docs.djangoproject.com/en/1.11/ref/databases/#mysql-sql-mode
	Operations to perform:
	Apply all migrations: account, admin, attachments, auth, authkeys, contenttypes, core, database, djcelery, feeder, search, sessions, sites, soapbox, socialaccount, taggit, tidings, users, w