sphinxcontrib-coderun 0.1.0__py3-none-any.whl

sphinxcontrib/__init__.py

@@ -0,0 +1,2 @@
+# namespace package
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

sphinxcontrib/coderun/__init__.py

@@ -0,0 +1,76 @@
+"""
+sphinxcontrib.coderun
+~~~~~~~~~~~~~~~~~~~~~
+Sphinx directive that renders a literalinclude code block with an embedded
+codapi "Run" button powered by a self-hosted codeapi instance.
+
+Usage in RST::
+
+    .. coderun:: path/to/file.c
+       :language: c
+       :sandbox: gcc
+       :url: https://codapi.example.com
+
+Global defaults in conf.py::
+
+    coderun_url     = 'https://codapi.example.com'
+    coderun_sandbox = 'gcc'
+"""
+
+import uuid
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.directives.code import LiteralInclude
+
+
+class CodeRunDirective(LiteralInclude):
+    """Like literalinclude but appends a codapi run widget after the code block."""
+
+    option_spec = {
+        **LiteralInclude.option_spec,
+        'sandbox': directives.unchanged,
+        'url': directives.unchanged,
+    }
+
+    def run(self):
+        result = super().run()
+        sandbox = self.options.get('sandbox') or self.env.config.coderun_sandbox
+        url = self.options.get('url') or self.env.config.coderun_url
+
+        # Wrap the code block in a div with a unique ID so the codapi selector
+        # can target just the <code> element — excluding any "Copy to clipboard"
+        # buttons that themes inject into the surrounding <pre>/<div>.
+        code_id = f"coderun-{uuid.uuid4().hex[:8]}"
+        wrapper_open = nodes.raw('', f'<div id="{code_id}">', format='html')
+        wrapper_close = nodes.raw('', '</div>', format='html')
+        snippet_html = (
+            f'<codapi-snippet sandbox="{sandbox}" url="{url}" '
+            f'editor="basic" selector="#{code_id} pre"></codapi-snippet>'
+        )
+        return [wrapper_open] + result + [wrapper_close, nodes.raw('', snippet_html, format='html')]
+
+
+def setup(app):
+    app.add_config_value('coderun_url', 'http://localhost:1313', 'html')
+    app.add_config_value('coderun_sandbox', 'gcc', 'html')
+    app.add_directive('coderun', CodeRunDirective)
+    app.add_css_file('coderun.css')
+    app.add_js_file(
+        'https://unpkg.com/@antonz/codapi@0.19.4/dist/snippet.js',
+        **{'type': 'module'},
+    )
+    app.connect('builder-inited', copy_static_files)
+    return {'version': '0.1', 'parallel_read_safe': True}
+
+
+def copy_static_files(app):
+    """Copy the bundled CSS into the build's _static directory."""
+    import os
+    import shutil
+    src = os.path.join(os.path.dirname(__file__), 'static', 'coderun.css')
+    if app.builder.format != 'html':
+        return
+    dst_dir = os.path.join(app.outdir, '_static')
+    os.makedirs(dst_dir, exist_ok=True)
+    shutil.copy(src, os.path.join(dst_dir, 'coderun.css'))

sphinxcontrib/coderun/static/coderun.css

@@ -0,0 +1,45 @@
+/* sphinxcontrib-coderun: codapi snippet widget styling */
+
+codapi-snippet {
+    display: block;
+    margin-top: 0.75rem;
+    margin-bottom: 1.5rem;
+}
+
+codapi-snippet .codapi-toolbar {
+    display: flex;
+    gap: 0.5rem;
+    padding: 0.5rem 0.75rem;
+    background: #f0f0f0;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+}
+
+codapi-snippet .codapi-toolbar button {
+    font-size: 0.8rem;
+    padding: 0.2rem 0.75rem;
+    cursor: pointer;
+    border: 1px solid #bbb;
+    border-radius: 3px;
+    background: #fff;
+}
+
+codapi-snippet .codapi-toolbar button:hover {
+    background: #e8e8e8;
+}
+
+codapi-snippet .codapi-output {
+    margin-top: 0.5rem;
+    padding: 0.75rem;
+    background: #1e1e1e;
+    color: #d4d4d4;
+    font-family: monospace;
+    font-size: 0.875rem;
+    border-radius: 4px;
+    white-space: pre-wrap;
+    word-break: break-word;
+}
+
+codapi-snippet .codapi-output.error {
+    color: #f44747;
+}

sphinxcontrib_coderun-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: sphinxcontrib-coderun
+Version: 0.1.0
+Summary: Sphinx directive that adds an interactive Run button to code files via a self-hosted codeapi instance
+Author-email: Senthil Kumaran <orsenthil@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/uthcode/sphinxcontrib-coderun
+Project-URL: Issues, https://github.com/uthcode/sphinxcontrib-coderun/issues
+Keywords: sphinx,codeapi,interactive,code,documentation
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sphinx>=5.0
+Dynamic: license-file
+
+# sphinxcontrib-coderun
+
+A Sphinx extension that adds an interactive **Run** button to code files in your
+documentation. Powered by a self-hosted [codeapi](https://github.com/nalgeon/codapi)
+instance — you bring your own server, this extension wires it into Sphinx.
+
+## How it works
+
+1. You self-host a [codeapi](https://github.com/nalgeon/codapi) server (supports C,
+   Python, Go, Rust, and [many more](https://github.com/nalgeon/codapi/tree/main/sandboxes)).
+2. You add `.. coderun::` directives to your `.rst` files.
+3. When a reader clicks **Run**, the code is sent to your codeapi server, executed in
+   an isolated sandbox, and the output appears inline on the page.
+
+Nothing is shared with third-party services — all execution happens on your own
+infrastructure.
+
+## Install
+
+```sh
+pip install sphinxcontrib-coderun
+```
+
+## Configuration
+
+In your `conf.py`:
+
+```python
+extensions = [..., "sphinxcontrib.coderun"]
+
+# URL of your self-hosted codeapi instance
+coderun_url = "https://codapi.example.com"
+
+# Default sandbox (matches a sandbox configured on your codeapi server)
+coderun_sandbox = "gcc"
+```
+
+Both settings can be overridden per-directive (see below).
+
+## Usage
+
+Replace `.. literalinclude::` with `.. coderun::` wherever you want a Run button:
+
+```rst
+.. coderun:: cprogs/hello.c
+   :language: c
+```
+
+Override the sandbox or URL for a specific snippet:
+
+```rst
+.. coderun:: examples/hello.py
+   :language: python
+   :sandbox: python
+   :url: https://codapi.example.com
+```
+
+All standard `literalinclude` options work — `:lines:`, `:linenos:`,
+`:emphasize-lines:`, etc.
+
+## Self-hosting codeapi
+
+You need a running codeapi instance that the browser can reach. Quickstart:
+
+```sh
+# Pull the server and a sandbox image
+docker pull nalgeon/codapi
+docker pull codapi/gcc   # or python, go, etc.
+
+# Run the server
+docker run -p 1313:1313 -v /path/to/config:/opt/codapi nalgeon/codapi
+```
+
+For production deployment (Kubernetes, TLS, rate limiting) see the
+[codeapi documentation](https://github.com/nalgeon/codapi/tree/main/docs).
+
+Point `coderun_url` at the public URL of your server and you're done.
+
+## Development
+
+### Project structure
+
+```
+sphinxcontrib-coderun/
+├── pyproject.toml
+├── LICENSE
+├── README.md
+└── sphinxcontrib/
+    ├── __init__.py               # namespace package
+    └── coderun/
+        ├── __init__.py           # directive + Sphinx setup()
+        └── static/
+            └── coderun.css       # Run button styling
+```
+
+### Local setup
+
+```sh
+git clone https://github.com/uthcode/sphinxcontrib-coderun
+cd sphinxcontrib-coderun
+pip install -e .
+```
+
+To test against a Sphinx project, add to its `conf.py`:
+
+```python
+extensions = [..., "sphinxcontrib.coderun"]
+coderun_url = "http://localhost:1313"   # local codeapi for dev
+coderun_sandbox = "gcc"
+```
+
+### Building a distribution
+
+```sh
+pip install build twine
+python -m build
+# produces dist/sphinxcontrib_coderun-X.Y.Z.tar.gz
+#          dist/sphinxcontrib_coderun-X.Y.Z-py3-none-any.whl
+```
+
+Validate before uploading:
+
+```sh
+python -m twine check dist/*
+```
+
+### Publishing to PyPI
+
+Create an API token at [pypi.org/manage/account/token](https://pypi.org/manage/account/token/)
+scoped to this project, then:
+
+```sh
+python -m twine upload dist/*
+# Username: __token__
+# Password: pypi-AgEI...
+```
+
+### Releasing a new version
+
+1. Bump `version` in `pyproject.toml`.
+2. Delete `dist/`.
+3. Run `python -m build`.
+4. Run `python -m twine upload dist/*`.
+
+## License
+
+MIT

sphinxcontrib_coderun-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+sphinxcontrib/__init__.py,sha256=De6UN4plnWZJpR_JYBKWd5rNJ_8QZ_8OFhDpZIYhDno,85
+sphinxcontrib/coderun/__init__.py,sha256=P_7V2rBfap-qCexf6lxF113USxBicZlMnU7ilmfu2BQ,2612
+sphinxcontrib/coderun/static/coderun.css,sha256=jkny-nc9R9_rCwcbhPM5_aqiuztsWBHhleSz-aAaIVw,912
+sphinxcontrib_coderun-0.1.0.dist-info/licenses/LICENSE,sha256=BqVYrAZl8XoVOYK2DY3M2uEvCm9wuL0iSyXo1LPEtwY,1072
+sphinxcontrib_coderun-0.1.0.dist-info/METADATA,sha256=odwGV5JLnC1Lvim1O-2CT_wGcFqULRW2U2J9cpchwO4,4436
+sphinxcontrib_coderun-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sphinxcontrib_coderun-0.1.0.dist-info/top_level.txt,sha256=VJrV3_vaiKQVgVpR0I1iecxoO0drzGu-M0j40PVP2QQ,14
+sphinxcontrib_coderun-0.1.0.dist-info/RECORD,,

sphinxcontrib_coderun-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sphinxcontrib_coderun-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Senthil Kumaran
+
+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.

sphinxcontrib_coderun-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sphinxcontrib