| Name | sphinxcontrib-katex JSON |
| Version |
0.9.9
JSON |
| download |
| home_page | |
| Summary | A Sphinx extension for rendering math in HTML pages |
| upload_time | 2023-10-16 07:30:16 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | The MIT License Copyright (c) 2017 Hagen Wierstorf Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
sphinx
latex
katex
math
documentation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
sphinxcontrib-katex
===================
|docs| |python-versions| |license|
A `Sphinx extension`_ for rendering math in HTML pages.
The extension uses `KaTeX`_ for rendering of math in HTML pages. It is designed
as a replacement for the built-in extension `sphinx.ext.mathjax`_, which uses
`MathJax`_ for rendering.
* **Documentation**: https://sphinxcontrib-katex.readthedocs.io/
* **Download**: https://pypi.org/project/sphinxcontrib-katex/#files
* **Development**: https://github.com/hagenw/sphinxcontrib-katex/
.. _Sphinx extension: http://www.sphinx-doc.org/en/master/extensions.html
.. _MathJax: https://www.mathjax.org
.. _KaTeX: https://khan.github.io/KaTeX/
.. _sphinx.ext.mathjax:
https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/mathjax.py
.. |docs| image:: https://readthedocs.org/projects/sphinxcontrib-katex/badge/
:target: https://sphinxcontrib-katex.readthedocs.io/
:alt: sphinxcontrib.katex's documentation on Read the Docs
.. |license| image:: https://img.shields.io/badge/license-MIT-green.svg
:target: https://github.com/hagenw/sphinxcontrib-katex/blob/main/LICENSE
:alt: sphinxcontrib.katex's MIT license
.. |python-versions| image:: https://img.shields.io/pypi/pyversions/sphinxcontrib-katex.svg
:target: https://pypi.org/project/sphinxcontrib-katex/
:alt: sphinxcontrib-katex's supported Python versions
Installation
------------
To install ``sphinxcontrib.katex`` into your Python virtual environment run:
.. code-block:: bash
$ pip install sphinxcontrib-katex
If you want to pre-render the math
by running Javascript on your server
instead of running it in the browsers of the users,
you have to install nodejs_.
.. _nodejs: https://nodejs.org/
Usage
-----
In ``conf.py`` of your Sphinx project, add the extension with:
.. code-block:: python
extensions = ['sphinxcontrib.katex']
To enable server side pre-rendering
add in addition
(nodejs_ installation needed):
.. code-block:: python
katex_prerender = True
See the Configuration section for all available settings.
.. _nodejs: https://nodejs.org/
Configuration
-------------
The behavior of ``sphinxcontrib.katex`` can be changed by configuration
entries in ``conf.py`` of your documentation project. In the following
all configuration entries are listed and their default values are shown.
.. code-block:: python
katex_css_path = \
'https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css'
katex_js_path = 'katex.min.js'
katex_autorender_path = 'auto-render.min.js'
katex_inline = [r'\(', r'\)']
katex_display = [r'\[', r'\]']
katex_prerender = False
katex_options = ''
The specific delimiters written to HTML when math mode is encountered are
controlled by the two lists ``katex_inline`` and ``katex_display``.
If ``katex_prerender`` is set to ``True`` the equations will be pre-rendered on
the server and loading of the page in the browser will be faster.
On your server you must have a ``katex`` executable installed and in your PATH
as described in the Installation section.
The string variable ``katex_options`` allows you to change all available
official `KaTeX rendering options`_, e.g.
.. code-block:: python
katex_options = r'''{
displayMode: true,
macros: {
"\\RR": "\\mathbb{R}"
}
}'''
You can also add `KaTeX auto-rendering options`_ to ``katex_options``, but be
aware that the ``delimiters`` entry should contain the entries of
``katex_inline`` and ``katex_display``.
.. _KaTeX rendering options:
https://khan.github.io/KaTeX/docs/options.html
.. _KaTeX auto-rendering options:
https://khan.github.io/KaTeX/docs/autorender.html
LaTeX Macros
------------
Most probably you want to add some of your LaTeX math commands for the
rendering. In KaTeX this is supported by LaTeX macros (``\def``).
You can use the ``katex_options`` configuration setting to add those:
.. code-block:: python
katex_options = r'''macros: {
"\\i": "\\mathrm{i}",
"\\e": "\\mathrm{e}^{#1}",
"\\vec": "\\mathbf{#1}",
"\\x": "\\vec{x}",
"\\d": "\\operatorname{d}\\!{}",
"\\dirac": "\\operatorname{\\delta}\\left(#1\\right)",
"\\scalarprod": "\\left\\langle#1,#2\\right\\rangle",
}'''
The disadvantage of this option is that those macros will be only available in
the HTML based `Sphinx builders`_. If you want to use them in the LaTeX based
builders as well you have to add them as the ``latex_macros`` setting in your
``conf.py`` and specify them using proper LaTeX syntax. Afterwards you can
include them via the ``sphinxcontrib.katex.latex_defs_to_katex_macros``
function into ``katex_options`` and add them to the LaTeX preamble:
.. code-block:: python
import sphinxcontrib.katex as katex
latex_macros = r"""
\def \i {\mathrm{i}}
\def \e #1{\mathrm{e}^{#1}}
\def \vec #1{\mathbf{#1}}
\def \x {\vec{x}}
\def \d {\operatorname{d}\!}
\def \dirac #1{\operatorname{\delta}\left(#1\right)}
\def \scalarprod #1#2{\left\langle#1,#2\right\rangle}
"""
# Translate LaTeX macros to KaTeX and add to options for HTML builder
katex_macros = katex.latex_defs_to_katex_macros(latex_macros)
katex_options = 'macros: {' + katex_macros + '}'
# Add LaTeX macros for LATEX builder
latex_elements = {'preamble': latex_macros}
.. _Sphinx builders: http://www.sphinx-doc.org/en/master/builders.html
Raw data
{
"_id": null,
"home_page": "",
"name": "sphinxcontrib-katex",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "sphinx,latex,katex,math,documentation",
"author": "",
"author_email": "Hagen Wierstorf <hagenw@posteo.de>",
"download_url": "https://files.pythonhosted.org/packages/37/cd/ce080239380ab842af89103ae69e728567dca09f2ad3bd623e8659ee96a7/sphinxcontrib-katex-0.9.9.tar.gz",
"platform": null,
"description": "sphinxcontrib-katex\n===================\n\n|docs| |python-versions| |license|\n\nA `Sphinx extension`_ for rendering math in HTML pages.\n\nThe extension uses `KaTeX`_ for rendering of math in HTML pages. It is designed\nas a replacement for the built-in extension `sphinx.ext.mathjax`_, which uses\n`MathJax`_ for rendering.\n\n* **Documentation**: https://sphinxcontrib-katex.readthedocs.io/\n\n* **Download**: https://pypi.org/project/sphinxcontrib-katex/#files\n\n* **Development**: https://github.com/hagenw/sphinxcontrib-katex/\n\n.. _Sphinx extension: http://www.sphinx-doc.org/en/master/extensions.html\n.. _MathJax: https://www.mathjax.org\n.. _KaTeX: https://khan.github.io/KaTeX/\n.. _sphinx.ext.mathjax:\n https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/mathjax.py\n\n.. |docs| image:: https://readthedocs.org/projects/sphinxcontrib-katex/badge/\n :target: https://sphinxcontrib-katex.readthedocs.io/\n :alt: sphinxcontrib.katex's documentation on Read the Docs\n.. |license| image:: https://img.shields.io/badge/license-MIT-green.svg\n :target: https://github.com/hagenw/sphinxcontrib-katex/blob/main/LICENSE\n :alt: sphinxcontrib.katex's MIT license\n.. |python-versions| image:: https://img.shields.io/pypi/pyversions/sphinxcontrib-katex.svg\n :target: https://pypi.org/project/sphinxcontrib-katex/\n :alt: sphinxcontrib-katex's supported Python versions\n\n\nInstallation\n------------\n\nTo install ``sphinxcontrib.katex`` into your Python virtual environment run:\n\n.. code-block:: bash\n\n $ pip install sphinxcontrib-katex\n\nIf you want to pre-render the math\nby running Javascript on your server\ninstead of running it in the browsers of the users,\nyou have to install nodejs_.\n\n.. _nodejs: https://nodejs.org/\n\n\nUsage\n-----\n\nIn ``conf.py`` of your Sphinx project, add the extension with:\n\n.. code-block:: python\n\n extensions = ['sphinxcontrib.katex']\n\nTo enable server side pre-rendering\nadd in addition\n(nodejs_ installation needed):\n\n.. code-block:: python\n\n katex_prerender = True\n\nSee the Configuration section for all available settings.\n\n.. _nodejs: https://nodejs.org/\n\n\nConfiguration\n-------------\n\nThe behavior of ``sphinxcontrib.katex`` can be changed by configuration\nentries in ``conf.py`` of your documentation project. In the following\nall configuration entries are listed and their default values are shown.\n\n.. code-block:: python\n\n katex_css_path = \\\n 'https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css'\n katex_js_path = 'katex.min.js'\n katex_autorender_path = 'auto-render.min.js'\n katex_inline = [r'\\(', r'\\)']\n katex_display = [r'\\[', r'\\]']\n katex_prerender = False\n katex_options = ''\n\nThe specific delimiters written to HTML when math mode is encountered are\ncontrolled by the two lists ``katex_inline`` and ``katex_display``.\n\nIf ``katex_prerender`` is set to ``True`` the equations will be pre-rendered on\nthe server and loading of the page in the browser will be faster.\nOn your server you must have a ``katex`` executable installed and in your PATH\nas described in the Installation section.\n\nThe string variable ``katex_options`` allows you to change all available\nofficial `KaTeX rendering options`_, e.g.\n\n.. code-block:: python\n\n katex_options = r'''{\n displayMode: true,\n macros: {\n \"\\\\RR\": \"\\\\mathbb{R}\"\n }\n }'''\n\nYou can also add `KaTeX auto-rendering options`_ to ``katex_options``, but be\naware that the ``delimiters`` entry should contain the entries of\n``katex_inline`` and ``katex_display``.\n\n.. _KaTeX rendering options:\n https://khan.github.io/KaTeX/docs/options.html\n.. _KaTeX auto-rendering options:\n https://khan.github.io/KaTeX/docs/autorender.html\n\n\nLaTeX Macros\n------------\n\nMost probably you want to add some of your LaTeX math commands for the\nrendering. In KaTeX this is supported by LaTeX macros (``\\def``).\nYou can use the ``katex_options`` configuration setting to add those:\n\n.. code-block:: python\n\n katex_options = r'''macros: {\n \"\\\\i\": \"\\\\mathrm{i}\",\n \"\\\\e\": \"\\\\mathrm{e}^{#1}\",\n \"\\\\vec\": \"\\\\mathbf{#1}\",\n \"\\\\x\": \"\\\\vec{x}\",\n \"\\\\d\": \"\\\\operatorname{d}\\\\!{}\",\n \"\\\\dirac\": \"\\\\operatorname{\\\\delta}\\\\left(#1\\\\right)\",\n \"\\\\scalarprod\": \"\\\\left\\\\langle#1,#2\\\\right\\\\rangle\",\n }'''\n\nThe disadvantage of this option is that those macros will be only available in\nthe HTML based `Sphinx builders`_. If you want to use them in the LaTeX based\nbuilders as well you have to add them as the ``latex_macros`` setting in your\n``conf.py`` and specify them using proper LaTeX syntax. Afterwards you can\ninclude them via the ``sphinxcontrib.katex.latex_defs_to_katex_macros``\nfunction into ``katex_options`` and add them to the LaTeX preamble:\n\n.. code-block:: python\n\n import sphinxcontrib.katex as katex\n\n latex_macros = r\"\"\"\n \\def \\i {\\mathrm{i}}\n \\def \\e #1{\\mathrm{e}^{#1}}\n \\def \\vec #1{\\mathbf{#1}}\n \\def \\x {\\vec{x}}\n \\def \\d {\\operatorname{d}\\!}\n \\def \\dirac #1{\\operatorname{\\delta}\\left(#1\\right)}\n \\def \\scalarprod #1#2{\\left\\langle#1,#2\\right\\rangle}\n \"\"\"\n\n # Translate LaTeX macros to KaTeX and add to options for HTML builder\n katex_macros = katex.latex_defs_to_katex_macros(latex_macros)\n katex_options = 'macros: {' + katex_macros + '}'\n\n # Add LaTeX macros for LATEX builder\n latex_elements = {'preamble': latex_macros}\n\n.. _Sphinx builders: http://www.sphinx-doc.org/en/master/builders.html\n",
"bugtrack_url": null,
"license": "The MIT License Copyright (c) 2017 Hagen Wierstorf Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "A Sphinx extension for rendering math in HTML pages",
"version": "0.9.9",
"project_urls": {
"documentation": "https://sphinxcontrib-katex.readthedocs.io",
"repository": "https://github.com/hagenw/sphinxcontrib-katex/"
},
"split_keywords": [
"sphinx",
"latex",
"katex",
"math",
"documentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8bfce86d11010ad35828b33f2730f68ec75148e68bb430959292e1e299f7d07d",
"md5": "8ef21c1dec601ec6f6ae6303c2daa9ef",
"sha256": "9b88f2b815ec04025ff0f96b50a22678bb9a186710aa34f20a308dd58fbb7f08"
},
"downloads": -1,
"filename": "sphinxcontrib_katex-0.9.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8ef21c1dec601ec6f6ae6303c2daa9ef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 96945,
"upload_time": "2023-10-16T07:30:13",
"upload_time_iso_8601": "2023-10-16T07:30:13.921894Z",
"url": "https://files.pythonhosted.org/packages/8b/fc/e86d11010ad35828b33f2730f68ec75148e68bb430959292e1e299f7d07d/sphinxcontrib_katex-0.9.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "37cdce080239380ab842af89103ae69e728567dca09f2ad3bd623e8659ee96a7",
"md5": "c72a9c0dd2fadf5fb2acd1ae5fdd7803",
"sha256": "d594c82df54b048d59d48e46b109f62217b311ab9b95208cab96d902f9a3fe29"
},
"downloads": -1,
"filename": "sphinxcontrib-katex-0.9.9.tar.gz",
"has_sig": false,
"md5_digest": "c72a9c0dd2fadf5fb2acd1ae5fdd7803",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 99711,
"upload_time": "2023-10-16T07:30:16",
"upload_time_iso_8601": "2023-10-16T07:30:16.256228Z",
"url": "https://files.pythonhosted.org/packages/37/cd/ce080239380ab842af89103ae69e728567dca09f2ad3bd623e8659ee96a7/sphinxcontrib-katex-0.9.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-16 07:30:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hagenw",
"github_project": "sphinxcontrib-katex",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "sphinxcontrib-katex"
}
