Skip to content

Commit 300bfe1

Browse files
So-CoolSo-Cool
committed
cssterm
0 parents  commit 300bfe1

22 files changed

+1070
-0
lines changed

‎.github/workflows/docs.yml

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: Build 🔧 the Jupyter Book 📖 and deploy 🚀 it to GitHub Pages
2+
on: push
3+
jobs:
4+
build-n-deploy:
5+
name: Build and deploy
6+
runs-on: ubuntu-18.04
7+
steps:
8+
- name: Checkout code 🛎️
9+
uses: actions/[email protected]
10+
with:
11+
persist-credentials: false
12+
submodules: 'recursive'
13+
- name: Set up Python 3.7 🐍
14+
uses: actions/setup-python@v1
15+
with:
16+
python-version: 3.7
17+
- name: Install dependencies 💾
18+
run: |
19+
pip install .
20+
pip install -r docs/requirements.txt
21+
- name: Build the book 🔧📖
22+
run: jb build -nW docs
23+
- name: Validate links ☑️🔗
24+
continue-on-error: true
25+
run: jb build -q --builder linkcheck docs
26+
- name: Deploy 🚀
27+
uses: JamesIves/[email protected]
28+
with:
29+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
30+
BRANCH: gh-pages
31+
FOLDER: docs/_build/html
32+
CLEAN: true

‎.github/workflows/pypi.yml

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Publish Python 🐍 distributions 📦 to PyPI
2+
on: push
3+
jobs:
4+
build-n-publish:
5+
name: Build and publish Python 🐍 distributions 📦 to PyPI
6+
runs-on: ubuntu-18.04
7+
steps:
8+
- name: Checkout code 🛎️
9+
uses: actions/[email protected]
10+
with:
11+
submodules: 'recursive'
12+
- name: Set up Python 3.7 🐍
13+
uses: actions/setup-python@v1
14+
with:
15+
python-version: 3.7
16+
- name: Install build dependencies 💾
17+
run: pip install wheel
18+
- name: Build a binary wheel and a source tarball distributions 📦
19+
run: python setup.py bdist_wheel sdist
20+
- name: Publish distribution 📦 to PyPI
21+
if: startsWith(github.ref, 'refs/tags')
22+
uses: pypa/gh-action-pypi-publish@master
23+
with:
24+
password: ${{ secrets.PYPI_API_TOKEN }}

‎.gitignore

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Python
2+
__pycache__
3+
*.egg-info
4+
dist
5+
build
6+
7+
# Mac OS
8+
.DS_Store
9+
10+
# Jupyter Book
11+
docs/_build

‎.gitmodules

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[submodule "sphinx_termynal/_static"]
2+
path = sphinx_term/_static/termynal
3+
url = https://github.com/ines/termynal.git
4+
[submodule "sphinx_term/_static/cssterm"]
5+
path = sphinx_term/_static/cssterm
6+
url = https://github.com/nstephens/cssterm.git

‎LICENCE

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
BSD 3-Clause License
2+
3+
Copyright (c) 2021, Kacper Sokol
4+
All rights reserved.
5+
6+
Redistribution and use in source and binary forms, with or without
7+
modification, are permitted provided that the following conditions are met:
8+
9+
* Redistributions of source code must retain the above copyright notice, this
10+
list of conditions and the following disclaimer.
11+
12+
* Redistributions in binary form must reproduce the above copyright notice,
13+
this list of conditions and the following disclaimer in the documentation
14+
and/or other materials provided with the distribution.
15+
16+
* Neither the name of the copyright holder nor the names of its
17+
contributors may be used to endorse or promote products derived from
18+
this software without specific prior written permission.
19+
20+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎MANIFEST.in

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
include README.md
2+
include LICENCE
3+
include sphinx_term/_static/README.md
4+
include sphinx_term/_static/termynal/termynal.css
5+
include sphinx_term/_static/termynal/termynal.min.js
6+
include sphinx_term/_static/cssterm/css/cssterm.css
7+
include sphinx_term/_static/cssterm/scripts/cssterm.js

‎README.md

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
[![Licence][licence-badge]][licence-link]
2+
[![Python][python-badge]][python-link]
3+
[![PyPI][pypi-badge]][pypi-link]
4+
[![Documentation][doc-badge]][doc-link]
5+
6+
[licence-badge]: https://img.shields.io/github/license/so-cool/sphinx-term.svg
7+
[licence-link]: https://github.com/so-cool/sphinx-term/blob/master/LICENCE
8+
[python-badge]: https://img.shields.io/badge/python-3.5-blue.svg
9+
[python-link]: https://github.com/so-cool/sphinx-term
10+
[pypi-badge]: https://img.shields.io/pypi/v/sphinx-term.svg
11+
[pypi-link]: https://pypi.org/project/sphinx-term
12+
[doc-badge]: https://img.shields.io/badge/read-documentation-blue.svg
13+
[doc-link]: https://so-cool.github.io/sphinx-term
14+
15+
# :computer: Terminal extension for Jupyter Book (and Sphinx) #
16+
17+
This repository holds *terminal* extensions for [Sphinx], designed to be used
18+
with the [Jupyter Book] platform.
19+
It implements **vivacious terminal transcripts** that can be easily embedded
20+
in your [Sphinx] documentation and [Jupyter Book] pages.
21+
The `sphinx-term` extension relies on two web terminal window packages:
22+
* [termynal]; and
23+
* [cssterm].
24+
25+
**This readme file holds a technical documentation of the `sphinx-term`
26+
extension.
27+
For a [Jupyter Book] user guide and usage example of the terminal boxes
28+
visit the [example page] hosted on GitHub Pages, the source of which is
29+
available in the [docs] folder of this repository.**
30+
31+
> This *readme* file uses [Jupyter Book]'s [MyST Markdown] syntax for **roles**
32+
and **directives** -- see [MyST overview] for more details.
33+
For use with [Sphinx], please refer to the [reStructuredText] syntax.
34+
35+
## :snake: Installing `sphinx-term` ##
36+
37+
To get started with `sphinx-term`, first install it via `pip`:
38+
```bash
39+
pip install sphinx-term
40+
```
41+
then, add the `cssterm` and/or `termynal` module of the `sphinx_term`
42+
extension to the Sphinx `extensions` list in your `conf.py`
43+
```Python
44+
...
45+
extensions = [
46+
'sphinx_term.cssterm',
47+
'sphinx_term.termynal'
48+
]
49+
...
50+
```
51+
52+
## :keyboard: cssterm directive ##
53+
54+
The [`sphinx_term.cssterm`](sphinx_term/cssterm.py) module defines the
55+
`cssterm` directive, which is used for building [cssterm] terminal windows.
56+
57+
### Usage ###
58+
59+
A *[cssterm] terminal box* is included with the `cssterm` directive:
60+
61+
````text
62+
```{cssterm} cssterm:my-id
63+
$ echo "My terminal transcript"
64+
My terminal transcript
65+
```
66+
````
67+
68+
Each [cssterm] box can be referenced with its name using the `ref` role,
69+
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
71+
syntax: `` {ref}`custom hyper-link text <cssterm:my-id>` ``.
72+
See the [MyST Markdown documentation] for more details.
73+
74+
### Configuration parameters ###
75+
76+
The `cssterm` extension uses one [Sphinx] configuration parameter:
77+
78+
* `sphinx_term_cssterm_dir` (**required** when loading the box content
79+
from a file) -- defines the path to a directory holding files with content
80+
(terminal transcript) of each terminal box.
81+
82+
### Arguments, parameters and content ###
83+
84+
Each [cssterm] box has one **required** argument that specifies
85+
the *unique* id of this particular terminal block.
86+
This id **must** start with the `cssterm:` prefix.
87+
The content of a [cssterm] box can **either** be provided explicitly within the
88+
directive, **or** -- when the content is left empty -- it is pulled from a
89+
terminal transcript file whose name is derived from the terminal box id,
90+
and which should be located in the directory specified via the
91+
`sphinx_term_cssterm_dir` configuration parameter.
92+
The terminal transcript file name is expected to be the [cssterm] block id
93+
**without** the `cssterm:` prefix and **with** the `.log` extension.
94+
For example, for a [cssterm] block with `cssterm:my_log` id, the terminal
95+
transcript file should be named `my_code.log`.
96+
The `sphinx_term.cssterm` [Sphinx] extension *monitors* the code files for
97+
changes and automatically regenerates the affected pages.
98+
99+
## :keyboard: termynal directive ##
100+
101+
*Work in progress.*
102+
103+
---
104+
105+
> The CSS and JS files used by this [Sphinx] extension are loaded as
106+
git submodules into the [`sphinx_term/_static`](sphinx_term/_static)
107+
directory of this repository.
108+
109+
[sphinx]: https://www.sphinx-doc.org/
110+
[jupyter book]: https://jupyterbook.org/
111+
[termynal]: https://github.com/ines/termynal
112+
[cssterm]: https://github.com/nstephens/cssterm
113+
[example page]: https://so-cool.github.io/sphinx-term
114+
[doc]: docs
115+
[myst markdown]: https://myst-parser.readthedocs.io/
116+
[myst overview]: https://jupyterbook.org/content/myst.html
117+
[reStructuredText]: https://docutils.sourceforge.io/rst.html
118+
[MyST Markdown documentation]: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#targets-and-cross-referencing

‎docs/.nojekyll

Whitespace-only changes.

‎docs/_config.yml

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
title: '<tt>sphinx-term</tt> documentation'
2+
author: >
3+
<a href="mailto:[email protected]">Kacper Sokol</a>
4+
copyright: '2021'
5+
logo: src/img/computer.svg
6+
7+
exclude_patterns:
8+
- .DS_Store
9+
- __pycache__
10+
11+
html:
12+
favicon: src/img/computer.svg
13+
use_edit_page_button: true
14+
use_repository_button: true
15+
use_issues_button: true
16+
extra_footer: >
17+
This <a href="https://jupyterbook.org/intro.html">Jupyter Book</a>
18+
documents the
19+
<a href="https://github.com/So-Cool/sphinx-term"><tt>sphinx-term</tt></a>
20+
Sphinx extension.
21+
The source of this document is available on
22+
<a href="https://github.com/So-Cool/sphinx-term/tree/master/docs">GitHub</a>.
23+
24+
extra_navbar: ''
25+
# google_analytics_id: ''
26+
home_page_in_navbar: true
27+
baseurl: 'https://so-cool.github.io/sphinx-term/'
28+
29+
parse:
30+
myst_enable_extensions:
31+
- colon_fence
32+
- dollarmath
33+
- linkify
34+
35+
repository:
36+
url: https://github.com/So-Cool/sphinx-term
37+
38+
sphinx:
39+
extra_extensions:
40+
- sphinx_term.cssterm
41+
config:
42+
html_extra_path:
43+
- ../README.md
44+
- ../LICENCE
45+
- .nojekyll
46+
numfig_format:
47+
figure: 'Figure %s'
48+
numfig_secnum_depth: 1
49+
# Configure Sphinx-copybutton
50+
# <https://sphinx-copybutton.readthedocs.io/en/latest/>
51+
copybutton_prompt_text: ''
52+
copybutton_only_copy_prompt_lines: false
53+
copybutton_remove_prompts: false
54+
# Configure Sphinx-term extension
55+
sphinx_term_cssterm_dir: src/cssterm_files/

‎docs/_toc.yml

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
format: jb-article
2+
root: src/sphinx_term
3+
4+
sections:
5+
- file: src/text/cssterm
6+
- url: https://github.com/So-Cool/sphinx-term
7+
title: 'sphinx-term extension'

‎docs/requirements.txt

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
jupyter-book>=0.11.0
2+
sphinx-term

‎docs/src/cssterm_files/demo.log

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
$ uname -a
2+
Linux ThinkPad-X230.localdomain 3.9.6-301.fc19.x86_64 #1 SMP Mon Jun 17 14:26:26 UTC 2013 x86_64 x86_64 x86_64 GNU/Linux
3+
4+
# dmesg | grep sd
5+
[135587.413741] sd 27:0:0:0: Attached scsi generic sg1 type 0
6+
[135587.416697] sd 27:0:0:0: [sdb] 2007040 512-byte logical blocks: (1.02 GB/980 MiB)
7+
[135587.418130] sd 27:0:0:0: [sdb] Write Protect is off
8+
[135587.418140] sd 27:0:0:0: [sdb] Mode Sense: 03 00 00 00
9+
[135587.418944] sd 27:0:0:0: [sdb] No Caching mode page present
10+
[135587.418947] sd 27:0:0:0: [sdb] Assuming drive cache: write through
11+
[135587.423205] sd 27:0:0:0: [sdb] No Caching mode page present
12+
[135587.423211] sd 27:0:0:0: [sdb] Assuming drive cache: write through
13+
[135587.424119] sdb: sdb1 sdb2
14+
[135587.428088] sd 27:0:0:0: [sdb] No Caching mode page present
15+
[135587.428094] sd 27:0:0:0: [sdb] Assuming drive cache: write through
16+
[135587.428098] sd 27:0:0:0: [sdb] Attached SCSI removable disk
17+
[135588.336077] SELinux: initialized (dev sdb1, type iso9660), uses genfs_contexts
18+
19+
# mkfs.ext4 /dev/sdb1
20+
mke2fs 1.41.12 (17-May-2010)
21+
Filesystem label=
22+
OS type: Linux
23+
Block size=4096 (log=2)
24+
Fragment size=4096 (log=2)
25+
Stride=0 blocks, Stripe width=0 blocks
26+
245280 inodes, 979456 blocks
27+
48972 blocks (5.00%) reserved for the super user
28+
First data block=0
29+
Maximum filesystem blocks=1006632960
30+
30 block groups
31+
32768 blocks per group, 32768 fragments per group
32+
8176 inodes per group
33+
Superblock backups stored on blocks:
34+
32768, 98304, 163840, 229376, 294912, 819200, 884736
35+
36+
Writing inode tables: done
37+
Creating journal (16384 blocks): done
38+
Writing superblocks and filesystem accounting information: done
39+
40+
This filesystem will be automatically checked every 20 mounts or
41+
180 days, whichever comes first. Use tune2fs -c or -i to override.

‎docs/src/cssterm_files/overwrite.log

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
$ pwd
2+
~/sphinx-term
3+
$ tree -d .
4+
.
5+
├── docs
6+
│   └── src
7+
│   ├── cssterm_files
8+
│   ├── img
9+
│   └── text
10+
├── sphinx_term
11+
│   └── _static
12+
│   ├── cssterm
13+
│   │   ├── css
14+
│   │   └── scripts
15+
│   └── termynal

‎docs/src/img/computer.svg

+19
Loading

0 commit comments

Comments
 (0)