Skip to content

Commit c8c4d2b

Browse files
mgeiermgeier
committed
DOC: Equation numbering and referencing
Closes #2.
1 parent 0776abe commit c8c4d2b

File tree

3 files changed

+117
-7
lines changed

3 files changed

+117
-7
lines changed

‎doc/conf.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,10 @@
9595
# '.Rmd': lambda s: jupytext.reads(s, '.Rmd'),
9696
#}
9797

98+
mathjax_config = {
99+
'TeX': {'equationNumbers': {'autoNumber': 'AMS', 'useLabelIds': True}},
100+
}
101+
98102
# -- The settings below this line are not specific to nbsphinx ------------
99103

100104
master_doc = 'index'

‎doc/markdown-cells.ipynb‎

Lines changed: 104 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,19 +39,118 @@
3939
"source": [
4040
"## Equations\n",
4141
"\n",
42-
"Equations can be formatted really nicely, either inline, like $\\text{e}^{i\\pi} = -1$, or on a separate line, like\n",
42+
"Inline equations like $\\text{e}^{i\\pi} = -1$\n",
43+
"can be created by putting a LaTeX expression between two dollar signs, like this:\n",
44+
"`$\\text{e}^{i\\pi} = -1$`."
45+
]
46+
},
47+
{
48+
"cell_type": "markdown",
49+
"metadata": {},
50+
"source": [
51+
"<div class=\"alert alert-info\">\n",
52+
"\n",
53+
"**Note:**\n",
54+
"\n",
55+
"Avoid leading and trailing spaces around math expressions, otherwise errors like the following will occur when Sphinx is running:\n",
56+
"\n",
57+
" ERROR: Unknown interpreted text role \"raw-latex\".\n",
58+
"\n",
59+
"See also the [pandoc docs](http://pandoc.org/MANUAL.html#math):\n",
60+
"\n",
61+
"> Anything between two `$` characters will be treated as TeX math. The opening `$` must have a non-space character immediately to its right, while the closing `$` must have a non-space character immediately to its left, and must not be followed immediately by a digit.\n",
62+
"\n",
63+
"</div>"
64+
]
65+
},
66+
{
67+
"cell_type": "markdown",
68+
"metadata": {},
69+
"source": [
70+
"Equations can also be displayed on their own line like this:\n",
71+
"\\begin{equation}\n",
72+
"\\int_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0).\n",
73+
"\\end{equation}\n",
74+
"\n",
75+
"This can be done by simply using one of the LaTeX math environments, like so:\n",
4376
"\n",
77+
"```\n",
4478
"\\begin{equation}\n",
4579
"\\int_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0)\n",
4680
"\\end{equation}\n",
81+
"```"
82+
]
83+
},
84+
{
85+
"cell_type": "markdown",
86+
"metadata": {},
87+
"source": [
88+
"### Automatic Equation Numbering\n",
89+
"\n",
90+
"This is not automatically enabled in Jupyter notebooks,\n",
91+
"but you can install a notebook extension in order to enable equation numbering:\n",
92+
"https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/equation-numbering/readme.html.\n",
93+
"\n",
94+
"Automatic Equation Numbering is enabled on http://nbviewer.jupyter.org/,\n",
95+
"see e.g. the latest version of this very notebook at the link http://nbviewer.jupyter.org/github/spatialaudio/nbsphinx/blob/master/doc/markdown-cells.ipynb.\n",
96+
"\n",
97+
"When using `nbsphinx`, you can use the following `mathjax_config` setting in your `conf.py` file\n",
98+
"to enable automatic equation numbering in HTML output.\n",
99+
"In LaTeX output, the equations are numbered by default.\n",
100+
"\n",
101+
"```python\n",
102+
"mathjax_config = {\n",
103+
" 'TeX': {'equationNumbers': {'autoNumber': 'AMS', 'useLabelIds': True}},\n",
104+
"}\n",
105+
"```\n",
106+
"\n",
107+
"You can use `\\label{...}` to give a unique label to an equation:\n",
108+
"\n",
109+
"\\begin{equation}\n",
110+
"\\phi = \\frac{1 + \\sqrt{5}}{2}\n",
111+
"\\label{golden-mean}\n",
112+
"\\end{equation}\n",
47113
"\n",
48-
"*Note:* Avoid leading and trailing spaces around math expressions, otherwise errors like the following will occur when Sphinx is running:\n",
114+
"```\n",
115+
"\\begin{equation}\n",
116+
"\\phi = \\frac{1 + \\sqrt{5}}{2}\n",
117+
"\\label{golden-mean}\n",
118+
"\\end{equation}\n",
119+
"```\n",
49120
"\n",
50-
" ERROR: Unknown interpreted text role \"raw-latex\".\n",
121+
"If automatic equation numbering is enabled,\n",
122+
"you can later reference that equation using its label.\n",
123+
"You can use `\\eqref{golden-mean}` for a reference with parentheses: \\eqref{golden-mean},\n",
124+
"or `\\ref{golden-mean}` for a reference without them: \\ref{golden-mean}.\n",
51125
"\n",
52-
"See also the [pandoc docs](http://pandoc.org/MANUAL.html#math):\n",
126+
"In HTML output, these equation references only work for equations within a single HTML page.\n",
127+
"In LaTeX output, equations from other notebooks can be referenced, e.g. \\eqref{fibonacci-recurrence}."
128+
]
129+
},
130+
{
131+
"cell_type": "markdown",
132+
"metadata": {},
133+
"source": [
134+
"### Manual Equation Numbering\n",
135+
"\n",
136+
"If you prefer to assign equation numbers (or some kind of names) manually,\n",
137+
"you can do so with `\\tag{...}`:\n",
138+
"\n",
139+
"\\begin{equation}\n",
140+
"a^2 + b^2 = c^2\n",
141+
"\\tag{99.4}\n",
142+
"\\label{pythagoras}\n",
143+
"\\end{equation}\n",
144+
"\n",
145+
"```\n",
146+
"\\begin{equation}\n",
147+
"a^2 + b^2 = c^2\n",
148+
"\\tag{99.4}\n",
149+
"\\label{pythagoras}\n",
150+
"\\end{equation}\n",
151+
"```\n",
53152
"\n",
54-
"> Anything between two `$` characters will be treated as TeX math. The opening `$` must have a non-space character immediately to its right, while the closing `$` must have a non-space character immediately to its left, and must not be followed immediately by a digit."
153+
"The above equation has the number \\ref{pythagoras}."
55154
]
56155
},
57156
{

‎doc/subdir/a-notebook-in-a-subdir.ipynb‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,13 @@
4848
"\n",
4949
"A link to a local file: [link](../images/notebook_icon.png).\n",
5050
"\n",
51+
"A random equation:\n",
52+
"\\begin{equation}\n",
53+
"F_n = F_{n-1} + F_{n-2}\n",
54+
"\\tag{08.15}\n",
55+
"\\label{fibonacci-recurrence}\n",
56+
"\\end{equation}\n",
57+
"\n",
5158
"## A Sub-Section\n",
5259
"\n",
5360
"This is just for testing inter-notebook links,\n",
@@ -71,9 +78,9 @@
7178
"name": "python",
7279
"nbconvert_exporter": "python",
7380
"pygments_lexer": "ipython3",
74-
"version": "3.6.4"
81+
"version": "3.6.7"
7582
}
7683
},
7784
"nbformat": 4,
78-
"nbformat_minor": 1
85+
"nbformat_minor": 2
7986
}

0 commit comments

Comments
 (0)