About this site¶

Installing Sphinx¶

Notes for installing Sphinx are provided here.

pip install sphinx
pip install sphinx --upgrade

Site builds¶

The site can be built from source on Ubuntu and Windows by navigating to the /emscripten/site directory and using the command:

make clean
make html

SDK Builds¶

SDK builds are virtually identical to Site builds. The main difference is that on SDK builds the home page has a clear notification that it is an SDK build.

SDK builds are enabled by enabling the sdkbuild tag. This is done through the SPHINXOPTS environment variable:

# Set the sdkbuild tag.
set SPHINXOPTS=-t sdkbuild
make html

# Unset SPHINXOPTS
set SPHINXOPTS=

Build version¶

The documentation version should match the Emscripten version for the current build. For a general site build this will be the latest tagged release as defined in Emscripten version. For an SDK build it will be the Emscripten version for the SDK.

The version and release information is used in a few places in the documentation, for example AUTHORS.

The version information is defined in conf.py — see variables version and release. These variables can be overridden by setting new values in the SPHINXOPTS environment variable. For example, to update the release variable through the command line on Windows:

# Set SPHINXOPTS
set SPHINXOPTS=-D release=6.40
make html

# Unset SPHINXOPTS
set SPHINXOPTS=

Style guide¶

This section has a few very brief recommendations to help authors use common style.

Spelling: Where possible use US-English spelling.

Avoid idiomatic expressions: These can be particularly confusing to non-native speakers (for example “putting your foot in your mouth” actually means “saying something embarrassing”).

Emphasis:

• Bold : use for file names, and UI/menu instructions (for example: “Press OK to do something”).
• Italic : use for tool names - e.g. Clang, emcc, Closure Compiler.
• monotype : use for inline code (where you can’t link to the API reference) and for demonstrating tool command line options.

Note

Other than the above rules, emphasis should be used sparingly.

Lists: Use a colon on the lead-in to the list where appropriate. Capitalize the first letter and use a full-stop for each item.

How to link to a document or heading¶

To link to a page, first define a globally unique reference before the page title (e.g. _my-page-reference) then link to it using the ref role as shown:

.. _my-page-reference:

My Page Title
=============

This is the text of the section.

To link to page use either of the options below:
        ref:`my-reference-label` - the link text is the heading name after the reference
        ref:`some text <my-reference-label>` - the link text is "some text"

This is a better approach than linking to documents using the :doc: role, because the links do not get broken if the articles are moved.

This approach is also recommended for linking to arbitrary headings in the site.

Recommended section/heading markup¶

reStructured text defines section headings using a separate line of punctuation characters after (and optionally before) the heading text. The line of characters must be at least as long as the heading. For example:

A heading
=========

Different punctuation characters are used to specify nested sections. Although the system does not mandate which punctuation character is used for each nested level, it is important to be consistent. The recommended heading levels are:

=======================================
Page title (top and bottom bars of "=")
=======================================

Level 1 heading (single bar of "=" below)
=========================================

Level 2 heading (single bar of "-" below)
-----------------------------------------

Level 3 heading (single bar of "+" below)
+++++++++++++++++++++++++++++++++++++++++

Level 4 heading (single bar of "~" below)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Working in markdown¶

New articles may be authored and discussed on the wiki using Markdown syntax before being included in the documentation set. The easiest way to convert these to restructured text is to use a tool like Pandoc.