Skip to content

Commit 1453b60

Browse files
chrisjsewellchrisjsewell
committed
✨ NEW: Initial implementation
1 parent 2c24f2d commit 1453b60

File tree

12 files changed

+563
-1
lines changed

12 files changed

+563
-1
lines changed

‎.pre-commit-config.yaml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# See https://pre-commit.com for more information
2+
# See https://pre-commit.com/hooks.html for more hooks
3+
repos:
4+
- repo: https://github.com/pre-commit/pre-commit-hooks
5+
rev: v4.4.0
6+
hooks:
7+
- id: trailing-whitespace
8+
- id: end-of-file-fixer
9+
- id: check-yaml
10+
11+
- repo: https://github.com/psf/black
12+
rev: 22.12.0
13+
hooks:
14+
- id: black
15+
16+
- repo: https://github.com/pycqa/isort
17+
rev: 5.11.4
18+
hooks:
19+
- id: isort
20+
21+
- repo: https://github.com/charliermarsh/ruff-pre-commit
22+
rev: v0.0.217
23+
hooks:
24+
- id: ruff
25+
args: ["--force-exclude"]

‎.readthedocs.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
version: 2
2+
3+
python:
4+
version: "3"
5+
install:
6+
- method: pip
7+
path: .
8+
extra_requirements:
9+
- docs
10+
11+
sphinx:
12+
builder: html
13+
fail_on_warning: true

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,5 @@
11
# sphinx-pyscript
2-
A sphinx extension for adding pyscript to a page
2+
3+
This is a Sphinx extension that allows you to use [PyScript](https://docs.pyscript.net) in your documentation.
4+
5+
See the documentation for details.

‎docs/conf.py‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
from datetime import date
2+
3+
from sphinx_pyscript import __version__
4+
5+
# -- Project information -----------------------------------------------------
6+
7+
project = "Sphinx PyScript"
8+
version = __version__
9+
copyright = f"{date.today().year}, Chris Sewell"
10+
author = "Chris Sewell"
11+
12+
# -- General configuration ---------------------------------------------------
13+
14+
extensions = [
15+
"myst_parser",
16+
"sphinx_pyscript",
17+
]
18+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
19+
myst_enable_extensions = ["deflist"]
20+
21+
# -- HTML output -------------------------------------------------
22+
23+
html_theme = "furo"
24+
html_theme_options = {
25+
"source_repository": "https://github.com/chrisjsewell/sphinx_pyscript/",
26+
"source_branch": "main",
27+
"source_directory": "docs/",
28+
}

‎docs/convert_json_to_toml.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
from js import document
2+
3+
input_textarea = document.querySelector("form textarea#input_text")
4+
output_textarea = document.querySelector("form textarea#output_text")
5+
6+
7+
def do_convert(event):
8+
result = event.srcElement.value.replace("a", "b")
9+
output_textarea.value = result
10+
11+
12+
input_textarea.oninput = do_convert

‎docs/example_md.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
py-config:
3+
splashscreen:
4+
autoclose: true
5+
packages:
6+
- matplotlib
7+
---
8+
9+
# Example with MyST
10+
11+
## `py-repl` and `py-terminal`
12+
13+
We can create a REPL which will output to a `div` and print `stdout` to a terminal with:
14+
15+
````md
16+
```{py-repl}
17+
:output: replOutput
18+
19+
print("hallo world")
20+
import matplotlib.pyplot as plt
21+
plt.plot([1, 2, 3])
22+
plt.gcf()
23+
```
24+
25+
<div id="replOutput"></div>
26+
27+
```{py-terminal}
28+
```
29+
````
30+
31+
Press `shift+enter` to run the code.
32+
33+
```{py-repl}
34+
:output: replOutput
35+
36+
print("hallo world")
37+
import matplotlib.pyplot as plt
38+
plt.plot([1, 2, 3])
39+
plt.gcf()
40+
```
41+
42+
<div id="replOutput"></div>
43+
44+
```{py-terminal}
45+
```
46+
47+
## `py-script` application
48+
49+
Here is a simple application to replace "a" with "b", using the `py-script` directive:
50+
51+
````md
52+
```{py-script}
53+
:file: convert_json_to_toml.py
54+
```
55+
56+
<form method="post">
57+
<label for="input_text" style="display: block">Input</label>
58+
<textarea id="input_text" name="input_text" style="width: 90%">a</textarea>
59+
<label for="output_text" style="display: block">Output</label>
60+
<textarea id="output_text" name="output_text" readonly="true" style="width: 90%">b</textarea>
61+
</form>
62+
````
63+
64+
with the following code:
65+
66+
```{literalinclude} convert_json_to_toml.py
67+
:language: python
68+
```
69+
70+
```{py-script}
71+
:file: convert_json_to_toml.py
72+
```
73+
74+
<form method="post">
75+
<label for="input_text" style="display: block">Input</label>
76+
<textarea id="input_text" name="input_text" style="width: 90%">a</textarea>
77+
<label for="output_text" style="display: block">Output</label>
78+
<textarea id="output_text" name="output_text" readonly="true" style="width: 90%">b</textarea>
79+
</form>

‎docs/example_rst.rst‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
.. py-config::
2+
3+
splashscreen:
4+
autoclose: true
5+
packages:
6+
- matplotlib
7+
8+
Example with RST
9+
================
10+
11+
`py-repl` and `py-terminal`
12+
----------------------------
13+
14+
We can create a REPL which will output to a `div` and print `stdout` to a terminal with:
15+
16+
.. code-block:: restructuredtext
17+
18+
.. py-repl::
19+
:output: replOutput
20+
21+
print("hallo world")
22+
import matplotlib.pyplot as plt
23+
plt.plot([1, 2, 3])
24+
plt.gcf()
25+
26+
.. raw:: html
27+
28+
<div id="replOutput"></div>
29+
30+
.. py-terminal::
31+
32+
Press `shift+enter` to run the code.
33+
34+
.. py-repl::
35+
:output: replOutput
36+
37+
print("hallo world")
38+
import matplotlib.pyplot as plt
39+
plt.plot([1, 2, 3])
40+
plt.gcf()
41+
42+
.. raw:: html
43+
44+
<div id="replOutput"></div>
45+
46+
.. py-terminal::
47+
48+
`py-script` application
49+
-----------------------
50+
51+
Here is a simple application to replace "a" with "b", using the `py-script` directive:
52+
53+
.. code-block:: restructuredtext
54+
55+
.. py-script::
56+
:file: convert_json_to_toml.py
57+
58+
.. raw:: html
59+
60+
<form method="post">
61+
<label for="input_text" style="display: block">Input</label>
62+
<textarea id="input_text" name="input_text" style="width: 90%">a</textarea>
63+
<label for="output_text" style="display: block">Output</label>
64+
<textarea id="output_text" name="output_text" readonly="true" style="width: 90%">b</textarea>
65+
</form>
66+
67+
With the following code:
68+
69+
.. literalinclude:: convert_json_to_toml.py
70+
:language: python
71+
72+
.. py-script::
73+
:file: convert_json_to_toml.py
74+
75+
.. raw:: html
76+
77+
<form method="post">
78+
<label for="input_text" style="display: block">Input</label>
79+
<textarea id="input_text" name="input_text" style="width: 90%">a</textarea>
80+
<label for="output_text" style="display: block">Output</label>
81+
<textarea id="output_text" name="output_text" readonly="true" style="width: 90%">b</textarea>
82+
</form>

‎docs/index.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Sphinx PyScript
2+
3+
This is a Sphinx extension that allows you to use [PyScript](https://docs.pyscript.net) in your documentation.
4+
5+
```{toctree}
6+
:hidden:
7+
example_md
8+
example_rst
9+
```
10+
11+
## Installation
12+
13+
Install with pip:
14+
15+
```bash
16+
pip install sphinx-pyscript
17+
```
18+
19+
## Usage
20+
21+
Add the extension to your `conf.py`:
22+
23+
```python
24+
extensions = [
25+
"sphinx_pyscript",
26+
]
27+
```
28+
29+
To load PyScript on a page, either use the `py-config` directive to load the [config](https://docs.pyscript.net/latest/reference/elements/py-config.html#) in YAML format:
30+
31+
```restructuredtext
32+
.. py-config::
33+
34+
splashscreen:
35+
autoclose: true
36+
packages:
37+
- matplotlib
38+
```
39+
40+
or with MyST, use the top-matter:
41+
42+
```yaml
43+
---
44+
py-config:
45+
splashscreen:
46+
autoclose: true
47+
packages:
48+
- matplotlib
49+
---
50+
```
51+
52+
See the examples for more details.
53+
54+
## Configuration
55+
56+
The extension has the following configuration options:
57+
58+
pyscript_js
59+
: The URL for the PyScript JavaScript file
60+
61+
pyscript_css
62+
: The URL for the PyScript CSS file

‎pyproject.toml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
[build-system]
2+
requires = ["flit_core >=3.2,<4"]
3+
build-backend = "flit_core.buildapi"
4+
5+
[project]
6+
name = "sphinx_pyscript"
7+
authors = [{name = "Chris Sewell", email = "[email protected]"}]
8+
readme = "README.md"
9+
license = {file = "LICENSE"}
10+
classifiers = [
11+
"Development Status :: 4 - Beta",
12+
"Framework :: Sphinx :: Extension",
13+
"Intended Audience :: Developers",
14+
"License :: OSI Approved :: MIT License",
15+
"Programming Language :: Python :: 3",
16+
]
17+
keywords = ["sphinx", "pyscript"]
18+
dynamic = ["version", "description"]
19+
requires-python = ">=3.7"
20+
dependencies = [
21+
"sphinx>4",
22+
"pyyaml",
23+
]
24+
25+
[project.urls]
26+
Home = "https://github.com/chrisjsewell/sphinx_pyscript"
27+
28+
[project.optional-dependencies]
29+
testing = [
30+
"pytest",
31+
"sphinx-pytest",
32+
]
33+
docs = [
34+
"myst-parser",
35+
"furo",
36+
]
37+
38+
[tool.isort]
39+
profile = "black"

0 commit comments

Comments
 (0)