Skip to content

Commit b400abe

Browse files
So-CoolSo-Cool
committed
termynal
1 parent eb314f9 commit b400abe

File tree

14 files changed

+1110
-10
lines changed

14 files changed

+1110
-10
lines changed

‎.github/workflows/docs.yml

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
name: Build 🔧 the Jupyter Book 📖 and deploy 🚀 it to GitHub Pages
2-
on: push
2+
on:
3+
push:
4+
branches:
5+
- master
36
jobs:
47
build-n-deploy:
58
name: Build and deploy

‎MANIFEST.in

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@ include README.md
22
include LICENCE
33
include sphinx_term/_static/README.md
44
include sphinx_term/_static/termynal/termynal.css
5-
include sphinx_term/_static/termynal/termynal.min.js
5+
include sphinx_term/_static/termynal/termynal.js
66
include sphinx_term/_static/cssterm/css/cssterm.css
77
include sphinx_term/_static/cssterm/scripts/cssterm.js

‎README.md

+99-2
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ My terminal transcript
6767

6868
Each [cssterm] box can be referenced with its name using the `ref` role,
6969
e.g., `` {ref}`cssterm:my-id` ``, which produces *terminal box* hyper-link.
70-
The default hyper-link text can be changed with with the folowing `ref` role
70+
The default hyper-link text can be changed with with the following `ref` role
7171
syntax: `` {ref}`custom hyper-link text <cssterm:my-id>` ``.
7272
See the [MyST Markdown documentation] for more details.
7373

@@ -98,7 +98,101 @@ changes and automatically regenerates the affected pages.
9898

9999
## :keyboard: termynal directive ##
100100

101-
*Work in progress.*
101+
The [`sphinx_term.termynal`](sphinx_term/termynal.py) module defines the
102+
`termynal` directive, which is used for building [termynal] terminal windows.
103+
104+
### Usage ###
105+
106+
A *[termynal] box* is included with the `termynal` directive:
107+
108+
````text
109+
```{termynal} termynal:my-id
110+
- value: echo "My terminal transcript"
111+
type: input
112+
- My terminal transcript
113+
```
114+
````
115+
116+
The content of the directive is a **yml-formatted list** of lines to be
117+
displayed by the terminal (i.e., the terminal transcript).
118+
Each element of this list can either be:
119+
- an **empty** element -- indicating a plain, empty line;
120+
- a **string** -- specifying a plain line of terminal *output* text; or
121+
- a **dictionary** -- defining more complex line style.
122+
123+
Each line defined as a *dictionary* supports the following **optional** keys:
124+
- `value` (default *empty string*) -- the content of the termynal
125+
line given as a string;
126+
- `type` (default *none*) -- the line type where:
127+
* `input` indicates that the termynal line is an input,
128+
* `progress` creates a progress bar (`value` is not required), and
129+
* *empty string* (`''`) or *undefined* to get a plain *output* line --
130+
the default behaviour;
131+
- `prompt` (default `$`) -- a string specifying the prompt style;
132+
- `progressPercent` (default `100`) -- the maximum percent of the
133+
`progress` bar;
134+
- `progressChar` (default `█`) -- the character used to build the
135+
`progress` bar (*see below for more details*);
136+
- `typeDelay` (default `90`) -- the delay between each typed
137+
character given in milliseconds (*see below for more details*); and
138+
- `cursor` (default `▋`) -- the character used as the cursor
139+
(*see below for more details*).
140+
141+
For more information about customising termynal lines refer to the official
142+
documentation of [termynal lines][termynal-line].
143+
144+
Each [termynal] box can be referenced with its name using the `ref` role,
145+
e.g., `` {ref}`termynal:my-id` ``, which produces *terminal box* hyper-link.
146+
The default hyper-link text can be changed with with the following `ref` role
147+
syntax: `` {ref}`custom hyper-link text <termynal:my-id>` ``.
148+
See the [MyST Markdown documentation] for more details.
149+
150+
### Configuration parameters ###
151+
152+
The `termynal` extension uses one [Sphinx] configuration parameter:
153+
154+
* `sphinx_term_termynal_dir` (**required** when loading the box content
155+
from a file) -- defines the path to a directory holding files with content
156+
(terminal transcript) of each terminal box.
157+
158+
### Arguments, parameters and content ###
159+
160+
Each [termynal] box has one **required** argument that specifies
161+
the *unique* id of this particular terminal block.
162+
This id **must** start with the `termynal:` prefix.
163+
The content of a [termynal] box can **either** be provided explicitly within
164+
the directive, **or** -- when the content is left empty -- it is pulled from a
165+
terminal transcript file whose name is derived from the terminal box id,
166+
and which should be located in the directory specified via the
167+
`sphinx_term_termynal_dir` configuration parameter.
168+
The terminal transcript file name is expected to be the [termynal] block id
169+
**without** the `termynal:` prefix and **with** the `.yml` extension.
170+
For example, for a [termynal] block with `termynal:my_log` id, the terminal
171+
transcript file should be named `my_code.yml`.
172+
The `sphinx_term.termynal` [Sphinx] extension *monitors* the code files for
173+
changes and automatically regenerates the affected pages.
174+
175+
The `termynal` directive takes a number of **optional** parameters
176+
(see the official documentation of [termynal boxes][termynal-conf] for more
177+
information):
178+
- `prefix` (default `ty`) -- the prefix used for data attributes;
179+
- `startDelay` (default `600`) -- the delay before animation,
180+
given in milliseconds;
181+
- `typeDelay` (default `90`) -- the delay between displaying each typed
182+
character, given in milliseconds;
183+
- `lineDelay` (default `1500`) -- the delay between displaying each line,
184+
given in milliseconds;
185+
- `progressLength` (default `40`) -- the number of characters used when
186+
displaying a progress bar;
187+
- `progressChar` (default `█`) -- the character used for building
188+
progress bars;
189+
- `cursor` (default `▋`) -- the character used for displaying the cursor;
190+
- `noInit` (default `false`) -- whether to initialise the animation when the
191+
termynal window is loaded.
192+
When set to `true`, the termynal window can be initialised by explicitly
193+
calling `Termynal.init()`; and
194+
- `lineData` (default `null`) -- the sequence used to dynamically load termynal
195+
lines at instantiation.
102196

103197
---
104198

@@ -110,6 +204,9 @@ changes and automatically regenerates the affected pages.
110204
[jupyter book]: https://jupyterbook.org/
111205
[termynal]: https://github.com/ines/termynal
112206
[cssterm]: https://github.com/nstephens/cssterm
207+
[termynal]: https://github.com/ines/termynal
208+
[termynal-conf]: https://github.com/ines/termynal#customising-termynal
209+
[termynal-line]: https://github.com/ines/termynal#prompts-and-animations for description
113210
[example page]: https://so-cool.github.io/sphinx-term
114211
[doc]: docs
115212
[myst markdown]: https://myst-parser.readthedocs.io/

‎docs/_config.yml

+2
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ repository:
3838
sphinx:
3939
extra_extensions:
4040
- sphinx_term.cssterm
41+
- sphinx_term.termynal
4142
config:
4243
html_extra_path:
4344
- ../README.md
@@ -53,3 +54,4 @@ sphinx:
5354
copybutton_remove_prompts: false
5455
# Configure Sphinx-term extension
5556
sphinx_term_cssterm_dir: src/cssterm_files/
57+
sphinx_term_termynal_dir: src/termynal_files/

‎docs/_toc.yml

+1
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@ root: src/sphinx_term
33

44
sections:
55
- file: src/text/cssterm
6+
- file: src/text/termynal
67
- url: https://github.com/So-Cool/sphinx-term
78
title: 'sphinx-term extension'

‎docs/src/sphinx_term.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -49,4 +49,4 @@ See the [`_config.yml`] file of this documentation for reference.
4949
[termynal]: https://github.com/ines/termynal
5050
[cssterm]: https://github.com/nstephens/cssterm
5151
[`README.md`]: https://github.com/So-Cool/sphinx-term#readme
52-
[`_config.yml`]: https://github.com/So-Cool/sphinx-term/blob/master/docs/_config.yml#L38
52+
[`_config.yml`]: https://github.com/So-Cool/sphinx-term/blob/master/docs/_config.yml#L38-L41

‎docs/src/termynal_files/example2.yml

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
- value: npm uninstall react
2+
type: input
3+
prompt: ▲
4+
- value: Are you sure you want to uninstall 'react'?
5+
- value: y
6+
type: input
7+
prompt: (y/n)
8+
typeDelay: 1000
9+
- type: progress
10+
progressChar: '·'
11+
- value: Uninstalled 'react'
12+
- value: node
13+
type: input
14+
prompt: ▲
15+
- value: Array(5).fill('🦄')
16+
type: input
17+
prompt: '>'
18+
- value: "['🦄', '🦄', '🦄', '🦄', '🦄']"
19+
- value: cd ~/repos
20+
type: input
21+
prompt: ▲
22+
- value: git checkout branch master
23+
type: input
24+
prompt: ▲ ~/repos
25+
- value: git commit -m "Fix things"
26+
type: input
27+
prompt: ▲ ~/repos (master)

‎docs/src/termynal_files/example3.yml

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
- value: npm uninstall react
2+
type: input
3+
prompt: ▲
4+
- value: Are you sure you want to uninstall 'react'?
5+
- value: y
6+
type: input
7+
prompt: (y/n)
8+
typeDelay: 1000
9+
- type: progress
10+
progressChar: '·'
11+
- value: Uninstalled 'react'
12+
- value: node
13+
type: input
14+
prompt: ▲
15+
- value: Array(5).fill('🦄')
16+
type: input
17+
prompt: '>'
18+
- value: "['🦄', '🦄', '🦄', '🦄', '🦄']"
19+
- value: cd ~/repos
20+
type: input
21+
prompt: ▲
22+
- value: git checkout branch master
23+
type: input
24+
prompt: ▲ ~/repos
25+
- value: git commit -m "Fix things"
26+
type: input
27+
prompt: ▲ ~/repos (master)

‎docs/src/text/cssterm.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ Darwin MacBook-Pro 19.6.0 Darwin Kernel Version 19.6.0: Thu May 6 00:48:39 PDT
5555

5656
This approach requires you to list the terminal output directly within the
5757
`cssterm` directive.
58-
Additionally, each [cssterm] window needs to be tagged with with an id prefixed
58+
Additionally, each [cssterm] window needs to be tagged with an id prefixed
5959
with `cssterm:`, e.g., `cssterm:local` for the
6060
{ref}`terminal box above <cssterm:local>`.
6161

@@ -162,7 +162,7 @@ E.g., see this {ref}`awesome terminal log <cssterm:local>`.
162162
[readme]: https://github.com/So-Cool/sphinx-term#readme
163163
[so-cool/sphinx-term]: https://github.com/So-Cool/sphinx-term
164164
[this directory]: https://github.com/So-Cool/sphinx-term/tree/master/docs/src/cssterm_files
165-
[`sphinx_term_cssterm_dir`]: https://github.com/So-Cool/sphinx-term/blob/master/docs/_config.yml#L55
165+
[`sphinx_term_cssterm_dir`]: https://github.com/So-Cool/sphinx-term/blob/master/docs/_config.yml#L56
166166
[`demo.log`]: https://github.com/So-Cool/sphinx-term/blob/master/docs/src/cssterm_files/demo.log
167167
[`ref` role]: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#targets-and-cross-referencing
168168
[`overwrite.log`]: https://github.com/So-Cool/sphinx-term/blob/master/docs/src/cssterm_files/overwrite.log

0 commit comments

Comments
 (0)