| Name | sphinx-term JSON |
| Version |
0.1
JSON |
| download |
| home_page | https://github.com/So-Cool/sphinx-term |
| Summary | A collection of Sphinx (and Jupyter Book) extensions for authoring vivacious terminal transcripts. |
| upload_time | 2021-07-01 18:02:49 |
| maintainer | Kacper Sokol |
| docs_url | None |
| author | |
| requires_python | ~=3.5 |
| license | new BSD |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[![Licence][licence-badge]][licence-link]
[![Python][python-badge]][python-link]
[![PyPI][pypi-badge]][pypi-link]
[![Documentation][doc-badge]][doc-link]
[licence-badge]: https://img.shields.io/github/license/so-cool/sphinx-term.svg
[licence-link]: https://github.com/so-cool/sphinx-term/blob/master/LICENCE
[python-badge]: https://img.shields.io/badge/python-3.5-blue.svg
[python-link]: https://github.com/so-cool/sphinx-term
[pypi-badge]: https://img.shields.io/pypi/v/sphinx-term.svg
[pypi-link]: https://pypi.org/project/sphinx-term
[doc-badge]: https://img.shields.io/badge/read-documentation-blue.svg
[doc-link]: https://so-cool.github.io/sphinx-term
# :computer: Terminal extension for Jupyter Book (and Sphinx) #
This repository holds *terminal* extensions for [Sphinx], designed to be used
with the [Jupyter Book] platform.
It implements **vivacious terminal transcripts** that can be easily embedded
in your [Sphinx] documentation and [Jupyter Book] pages.
The `sphinx-term` extension relies on two web terminal window packages:
* [termynal]; and
* [cssterm].
**This readme file holds a technical documentation of the `sphinx-term`
extension.
For a [Jupyter Book] user guide and usage example of the terminal boxes
visit the [example page] hosted on GitHub Pages, the source of which is
available in the [docs] folder of this repository.**
> This *readme* file uses [Jupyter Book]'s [MyST Markdown] syntax for **roles**
and **directives** -- see [MyST overview] for more details.
For use with [Sphinx], please refer to the [reStructuredText] syntax.
## :snake: Installing `sphinx-term` ##
To get started with `sphinx-term`, first install it via `pip`:
```bash
pip install sphinx-term
```
then, add the `cssterm` and/or `termynal` module of the `sphinx_term`
extension to the Sphinx `extensions` list in your `conf.py`
```Python
...
extensions = [
'sphinx_term.cssterm',
'sphinx_term.termynal'
]
...
```
## :keyboard: cssterm directive ##
The [`sphinx_term.cssterm`](sphinx_term/cssterm.py) module defines the
`cssterm` directive, which is used for building [cssterm] terminal windows.
### Usage ###
A *[cssterm] terminal box* is included with the `cssterm` directive:
````text
```{cssterm} cssterm:my-id
$ echo "My terminal transcript"
My terminal transcript
```
````
Each [cssterm] box can be referenced with its name using the `ref` role,
e.g., `` {ref}`cssterm:my-id` ``, which produces *terminal box* hyper-link.
The default hyper-link text can be changed with with the following `ref` role
syntax: `` {ref}`custom hyper-link text <cssterm:my-id>` ``.
See the [MyST Markdown documentation] for more details.
### Configuration parameters ###
The `cssterm` extension uses one [Sphinx] configuration parameter:
* `sphinx_term_cssterm_dir` (**required** when loading the box content
from a file) -- defines the path to a directory holding files with content
(terminal transcript) of each terminal box.
### Arguments, parameters and content ###
Each [cssterm] box has one **required** argument that specifies
the *unique* id of this particular terminal block.
This id **must** start with the `cssterm:` prefix.
The content of a [cssterm] box can **either** be provided explicitly within the
directive, **or** -- when the content is left empty -- it is pulled from a
terminal transcript file whose name is derived from the terminal box id,
and which should be located in the directory specified via the
`sphinx_term_cssterm_dir` configuration parameter.
The terminal transcript file name is expected to be the [cssterm] block id
**without** the `cssterm:` prefix and **with** the `.log` extension.
For example, for a [cssterm] block with `cssterm:my_log` id, the terminal
transcript file should be named `my_code.log`.
The `sphinx_term.cssterm` [Sphinx] extension *monitors* the code files for
changes and automatically regenerates the affected pages.
## :keyboard: termynal directive ##
The [`sphinx_term.termynal`](sphinx_term/termynal.py) module defines the
`termynal` directive, which is used for building [termynal] terminal windows.
### Usage ###
A *[termynal] box* is included with the `termynal` directive:
````text
```{termynal} termynal:my-id
- value: echo "My terminal transcript"
type: input
- My terminal transcript
```
````
The content of the directive is a **yml-formatted list** of lines to be
displayed by the terminal (i.e., the terminal transcript).
Each element of this list can either be:
- an **empty** element -- indicating a plain, empty line;
- a **string** -- specifying a plain line of terminal *output* text; or
- a **dictionary** -- defining more complex line style.
Each line defined as a *dictionary* supports the following **optional** keys:
- `value` (default *empty string*) -- the content of the termynal
line given as a string;
- `type` (default *none*) -- the line type where:
* `input` indicates that the termynal line is an input,
* `progress` creates a progress bar (`value` is not required), and
* *empty string* (`''`) or *undefined* to get a plain *output* line --
the default behaviour;
- `prompt` (default `$`) -- a string specifying the prompt style;
- `progressPercent` (default `100`) -- the maximum percent of the
`progress` bar;
- `progressChar` (default `█`) -- the character used to build the
`progress` bar (*see below for more details*);
- `typeDelay` (default `90`) -- the delay between each typed
character given in milliseconds (*see below for more details*); and
- `cursor` (default `▋`) -- the character used as the cursor
(*see below for more details*).
For more information about customising termynal lines refer to the official
documentation of [termynal lines][termynal-line].
Each [termynal] box can be referenced with its name using the `ref` role,
e.g., `` {ref}`termynal:my-id` ``, which produces *terminal box* hyper-link.
The default hyper-link text can be changed with with the following `ref` role
syntax: `` {ref}`custom hyper-link text <termynal:my-id>` ``.
See the [MyST Markdown documentation] for more details.
### Configuration parameters ###
The `termynal` extension uses one [Sphinx] configuration parameter:
* `sphinx_term_termynal_dir` (**required** when loading the box content
from a file) -- defines the path to a directory holding files with content
(terminal transcript) of each terminal box.
### Arguments, parameters and content ###
Each [termynal] box has one **required** argument that specifies
the *unique* id of this particular terminal block.
This id **must** start with the `termynal:` prefix.
The content of a [termynal] box can **either** be provided explicitly within
the directive, **or** -- when the content is left empty -- it is pulled from a
terminal transcript file whose name is derived from the terminal box id,
and which should be located in the directory specified via the
`sphinx_term_termynal_dir` configuration parameter.
The terminal transcript file name is expected to be the [termynal] block id
**without** the `termynal:` prefix and **with** the `.yml` extension.
For example, for a [termynal] block with `termynal:my_log` id, the terminal
transcript file should be named `my_code.yml`.
The `sphinx_term.termynal` [Sphinx] extension *monitors* the code files for
changes and automatically regenerates the affected pages.
The `termynal` directive takes a number of **optional** parameters
(see the official documentation of [termynal boxes][termynal-conf] for more
information):
- `prefix` (default `ty`) -- the prefix used for data attributes;
- `startDelay` (default `600`) -- the delay before animation,
given in milliseconds;
- `typeDelay` (default `90`) -- the delay between displaying each typed
character, given in milliseconds;
- `lineDelay` (default `1500`) -- the delay between displaying each line,
given in milliseconds;
- `progressLength` (default `40`) -- the number of characters used when
displaying a progress bar;
- `progressChar` (default `█`) -- the character used for building
progress bars;
- `cursor` (default `▋`) -- the character used for displaying the cursor;
- `noInit` (default `false`) -- whether to initialise the animation when the
termynal window is loaded.
When set to `true`, the termynal window can be initialised by explicitly
calling `Termynal.init()`; and
- `lineData` (default `null`) -- the sequence used to dynamically load termynal
lines at instantiation.
---
> The CSS and JS files used by this [Sphinx] extension are loaded as
git submodules into the [`sphinx_term/_static`](sphinx_term/_static)
directory of this repository.
[sphinx]: https://www.sphinx-doc.org/
[jupyter book]: https://jupyterbook.org/
[termynal]: https://github.com/ines/termynal
[cssterm]: https://github.com/nstephens/cssterm
[termynal]: https://github.com/ines/termynal
[termynal-conf]: https://github.com/ines/termynal#customising-termynal
[termynal-line]: https://github.com/ines/termynal#prompts-and-animations for description
[example page]: https://so-cool.github.io/sphinx-term
[doc]: docs
[myst markdown]: https://myst-parser.readthedocs.io/
[myst overview]: https://jupyterbook.org/content/myst.html
[reStructuredText]: https://docutils.sourceforge.io/rst.html
[MyST Markdown documentation]: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#targets-and-cross-referencing
Raw data
{
"_id": null,
"home_page": "https://github.com/So-Cool/sphinx-term",
"name": "sphinx-term",
"maintainer": "Kacper Sokol",
"docs_url": null,
"requires_python": "~=3.5",
"maintainer_email": "ks1591@my.bristol.ac.uk",
"keywords": "",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/19/5c/915c424f29d9be00d6fea1cc732b0165a402d1dddfbd327e7f45a31db9da/sphinx-term-0.1.tar.gz",
"platform": "",
"description": "[![Licence][licence-badge]][licence-link]\n[![Python][python-badge]][python-link]\n[![PyPI][pypi-badge]][pypi-link]\n[![Documentation][doc-badge]][doc-link]\n\n[licence-badge]: https://img.shields.io/github/license/so-cool/sphinx-term.svg\n[licence-link]: https://github.com/so-cool/sphinx-term/blob/master/LICENCE\n[python-badge]: https://img.shields.io/badge/python-3.5-blue.svg\n[python-link]: https://github.com/so-cool/sphinx-term\n[pypi-badge]: https://img.shields.io/pypi/v/sphinx-term.svg\n[pypi-link]: https://pypi.org/project/sphinx-term\n[doc-badge]: https://img.shields.io/badge/read-documentation-blue.svg\n[doc-link]: https://so-cool.github.io/sphinx-term\n\n# :computer: Terminal extension for Jupyter Book (and Sphinx) #\n\nThis repository holds *terminal* extensions for [Sphinx], designed to be used\nwith the [Jupyter Book] platform.\nIt implements **vivacious terminal transcripts** that can be easily embedded\nin your [Sphinx] documentation and [Jupyter Book] pages.\nThe `sphinx-term` extension relies on two web terminal window packages:\n* [termynal]; and\n* [cssterm].\n\n**This readme file holds a technical documentation of the `sphinx-term`\nextension.\nFor a [Jupyter Book] user guide and usage example of the terminal boxes\nvisit the [example page] hosted on GitHub Pages, the source of which is\navailable in the [docs] folder of this repository.**\n\n> This *readme* file uses [Jupyter Book]'s [MyST Markdown] syntax for **roles**\n and **directives** -- see [MyST overview] for more details.\n For use with [Sphinx], please refer to the [reStructuredText] syntax.\n\n## :snake: Installing `sphinx-term` ##\n\nTo get started with `sphinx-term`, first install it via `pip`:\n```bash\npip install sphinx-term\n```\nthen, add the `cssterm` and/or `termynal` module of the `sphinx_term`\nextension to the Sphinx `extensions` list in your `conf.py`\n```Python\n...\nextensions = [\n 'sphinx_term.cssterm',\n 'sphinx_term.termynal'\n]\n...\n```\n\n## :keyboard: cssterm directive ##\n\nThe [`sphinx_term.cssterm`](sphinx_term/cssterm.py) module defines the\n`cssterm` directive, which is used for building [cssterm] terminal windows.\n\n### Usage ###\n\nA *[cssterm] terminal box* is included with the `cssterm` directive:\n\n````text\n```{cssterm} cssterm:my-id\n$ echo \"My terminal transcript\"\nMy terminal transcript\n```\n````\n\nEach [cssterm] box can be referenced with its name using the `ref` role,\ne.g., `` {ref}`cssterm:my-id` ``, which produces *terminal box* hyper-link.\nThe default hyper-link text can be changed with with the following `ref` role\nsyntax: `` {ref}`custom hyper-link text <cssterm:my-id>` ``.\nSee the [MyST Markdown documentation] for more details.\n\n### Configuration parameters ###\n\nThe `cssterm` extension uses one [Sphinx] configuration parameter:\n\n* `sphinx_term_cssterm_dir` (**required** when loading the box content\n from a file) -- defines the path to a directory holding files with content\n (terminal transcript) of each terminal box.\n\n### Arguments, parameters and content ###\n\nEach [cssterm] box has one **required** argument that specifies\nthe *unique* id of this particular terminal block.\nThis id **must** start with the `cssterm:` prefix.\nThe content of a [cssterm] box can **either** be provided explicitly within the\ndirective, **or** -- when the content is left empty -- it is pulled from a\nterminal transcript file whose name is derived from the terminal box id,\nand which should be located in the directory specified via the\n`sphinx_term_cssterm_dir` configuration parameter.\nThe terminal transcript file name is expected to be the [cssterm] block id\n**without** the `cssterm:` prefix and **with** the `.log` extension.\nFor example, for a [cssterm] block with `cssterm:my_log` id, the terminal\ntranscript file should be named `my_code.log`.\nThe `sphinx_term.cssterm` [Sphinx] extension *monitors* the code files for\nchanges and automatically regenerates the affected pages.\n\n## :keyboard: termynal directive ##\n\nThe [`sphinx_term.termynal`](sphinx_term/termynal.py) module defines the\n`termynal` directive, which is used for building [termynal] terminal windows.\n\n### Usage ###\n\nA *[termynal] box* is included with the `termynal` directive:\n\n````text\n```{termynal} termynal:my-id\n- value: echo \"My terminal transcript\"\n type: input\n- My terminal transcript\n```\n````\n\nThe content of the directive is a **yml-formatted list** of lines to be\ndisplayed by the terminal (i.e., the terminal transcript).\nEach element of this list can either be:\n- an **empty** element -- indicating a plain, empty line;\n- a **string** -- specifying a plain line of terminal *output* text; or\n- a **dictionary** -- defining more complex line style.\n\nEach line defined as a *dictionary* supports the following **optional** keys:\n- `value` (default *empty string*) -- the content of the termynal\n line given as a string;\n- `type` (default *none*) -- the line type where:\n * `input` indicates that the termynal line is an input,\n * `progress` creates a progress bar (`value` is not required), and\n * *empty string* (`''`) or *undefined* to get a plain *output* line --\n the default behaviour;\n- `prompt` (default `$`) -- a string specifying the prompt style;\n- `progressPercent` (default `100`) -- the maximum percent of the\n `progress` bar;\n- `progressChar` (default `\u2588`) -- the character used to build the\n `progress` bar (*see below for more details*);\n- `typeDelay` (default `90`) -- the delay between each typed\n character given in milliseconds (*see below for more details*); and\n- `cursor` (default `\u258b`) -- the character used as the cursor\n (*see below for more details*).\n\nFor more information about customising termynal lines refer to the official\ndocumentation of [termynal lines][termynal-line].\n\nEach [termynal] box can be referenced with its name using the `ref` role,\ne.g., `` {ref}`termynal:my-id` ``, which produces *terminal box* hyper-link.\nThe default hyper-link text can be changed with with the following `ref` role\nsyntax: `` {ref}`custom hyper-link text <termynal:my-id>` ``.\nSee the [MyST Markdown documentation] for more details.\n\n### Configuration parameters ###\n\nThe `termynal` extension uses one [Sphinx] configuration parameter:\n\n* `sphinx_term_termynal_dir` (**required** when loading the box content\n from a file) -- defines the path to a directory holding files with content\n (terminal transcript) of each terminal box.\n\n### Arguments, parameters and content ###\n\nEach [termynal] box has one **required** argument that specifies\nthe *unique* id of this particular terminal block.\nThis id **must** start with the `termynal:` prefix.\nThe content of a [termynal] box can **either** be provided explicitly within\nthe directive, **or** -- when the content is left empty -- it is pulled from a\nterminal transcript file whose name is derived from the terminal box id,\nand which should be located in the directory specified via the\n`sphinx_term_termynal_dir` configuration parameter.\nThe terminal transcript file name is expected to be the [termynal] block id\n**without** the `termynal:` prefix and **with** the `.yml` extension.\nFor example, for a [termynal] block with `termynal:my_log` id, the terminal\ntranscript file should be named `my_code.yml`.\nThe `sphinx_term.termynal` [Sphinx] extension *monitors* the code files for\nchanges and automatically regenerates the affected pages.\n\nThe `termynal` directive takes a number of **optional** parameters\n(see the official documentation of [termynal boxes][termynal-conf] for more\ninformation):\n- `prefix` (default `ty`) -- the prefix used for data attributes;\n- `startDelay` (default `600`) -- the delay before animation,\n given in milliseconds;\n- `typeDelay` (default `90`) -- the delay between displaying each typed\n character, given in milliseconds;\n- `lineDelay` (default `1500`) -- the delay between displaying each line,\n given in milliseconds;\n- `progressLength` (default `40`) -- the number of characters used when\n displaying a progress bar;\n- `progressChar` (default `\u2588`) -- the character used for building\n progress bars;\n- `cursor` (default `\u258b`) -- the character used for displaying the cursor;\n- `noInit` (default `false`) -- whether to initialise the animation when the\n termynal window is loaded.\n When set to `true`, the termynal window can be initialised by explicitly\n calling `Termynal.init()`; and\n- `lineData` (default `null`) -- the sequence used to dynamically load termynal\n lines at instantiation.\n\n---\n\n> The CSS and JS files used by this [Sphinx] extension are loaded as\n git submodules into the [`sphinx_term/_static`](sphinx_term/_static)\n directory of this repository.\n\n[sphinx]: https://www.sphinx-doc.org/\n[jupyter book]: https://jupyterbook.org/\n[termynal]: https://github.com/ines/termynal\n[cssterm]: https://github.com/nstephens/cssterm\n[termynal]: https://github.com/ines/termynal\n[termynal-conf]: https://github.com/ines/termynal#customising-termynal\n[termynal-line]: https://github.com/ines/termynal#prompts-and-animations for description\n[example page]: https://so-cool.github.io/sphinx-term\n[doc]: docs\n[myst markdown]: https://myst-parser.readthedocs.io/\n[myst overview]: https://jupyterbook.org/content/myst.html\n[reStructuredText]: https://docutils.sourceforge.io/rst.html\n[MyST Markdown documentation]: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#targets-and-cross-referencing\n\n\n",
"bugtrack_url": null,
"license": "new BSD",
"summary": "A collection of Sphinx (and Jupyter Book) extensions for authoring vivacious terminal transcripts.",
"version": "0.1",
"project_urls": {
"Download": "https://pypi.org/project/sphinx-term/#files",
"Homepage": "https://github.com/So-Cool/sphinx-term"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "380e5c5bc93c6977b27a2d81cdc167432613d11302dc3faac4ec7399a497f385",
"md5": "80a2133da4f1029c90e112cb7689c251",
"sha256": "71fbc006c0e9f2e979388fa16fd2a3ccae86f12db744abbe457dbea44892b578"
},
"downloads": -1,
"filename": "sphinx_term-0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "80a2133da4f1029c90e112cb7689c251",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.5",
"size": 22367,
"upload_time": "2021-07-01T18:02:48",
"upload_time_iso_8601": "2021-07-01T18:02:48.578182Z",
"url": "https://files.pythonhosted.org/packages/38/0e/5c5bc93c6977b27a2d81cdc167432613d11302dc3faac4ec7399a497f385/sphinx_term-0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "195c915c424f29d9be00d6fea1cc732b0165a402d1dddfbd327e7f45a31db9da",
"md5": "58ce7c67124cdb169e122b403d000c4c",
"sha256": "f4f83f62b8ae70cabbc44b6a85d923e0410345aed43570f959e4284e47e22241"
},
"downloads": -1,
"filename": "sphinx-term-0.1.tar.gz",
"has_sig": false,
"md5_digest": "58ce7c67124cdb169e122b403d000c4c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.5",
"size": 20879,
"upload_time": "2021-07-01T18:02:49",
"upload_time_iso_8601": "2021-07-01T18:02:49.883674Z",
"url": "https://files.pythonhosted.org/packages/19/5c/915c424f29d9be00d6fea1cc732b0165a402d1dddfbd327e7f45a31db9da/sphinx-term-0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-07-01 18:02:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "So-Cool",
"github_project": "sphinx-term",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-term"
}
