feat: Render code block for highlight.js

CHANGES.rst

@@ -2,9 +2,9 @@
 Change logs
 ===========
 
-v0.0.0
+v0.0.1
 ======
 
-:date: 2023-05-01
+:date: 2023-10-21
 
-Initial commit.
+First release.

README.rst

@@ -7,6 +7,23 @@ Override code-block output for highlight.js
 Getting started
 ===============
 
-.. code: console
+.. code:: console
 
    pip install atsphinx-highlightjs
+
+Usage
+=====
+
+Set extension into your ``conf.py`` of Sphinx documentation.
+
+.. code:: python
+
+   extensions = [
+       # Add extension with others.
+       "atsphinx.highlightjs",
+   ]
+
+License
+=======
+
+Apache-2.0 license. Please see `LICENSE <./LICENSE>`_.

docs/conf.py

@@ -9,11 +9,13 @@
 
 # -- General configuration
 extensions = [
-    "sphinx.ext.todo",
+    "atsphinx.highlightjs",
 ]
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # -- Options for HTML output
 html_theme = "alabaster"
 html_static_path = ["_static"]
+
+# -- Options for extensions

docs/index.rst

@@ -5,19 +5,39 @@ atsphinx-highlightjs
 Overview
 ========
 
-.. todo:: Write it
+Sphinx uses `Pygments <https://pygments.org/>`_ to hilight code syntax.
+
+This extension overrides behavior of highlighting of code for using `highlight.js <https://highlightjs.org/>`_.
 
 Installation
 ============
 
-.. todo:: Write it
+You can install from PyPI.
+
+.. code:: console
+
+   pip install atsphinx-highlightjs
 
 Usage
 =====
 
-.. todo:: Write it
+Basic usage
+-----------
+
+When you set extension into your ``conf.py`` of documentation,
+builder changes behaviors of code highlightings.
+
+.. code:: python
+
+   # Your conf.py
+   extensions = [
+       "atsphinx.highlightjs",
+   ]
+
+Please see HTML source, this includes only ``<pre><code>`` element only
+(if using Pygments, it renders parts of contents).
 
 Configuration
 =============
 
-.. todo:: Write it
+.. note:: Not yet exists.

src/atsphinx/highlightjs/__init__.py

@@ -0,0 +1,49 @@
+"""Override code-block output for highlight.js"""
+from pathlib import Path
+
+from docutils import nodes
+from sphinx.application import Sphinx
+from sphinx.config import Config
+from sphinx.util.docutils import SphinxTranslator
+
+__version__ = "0.0.0"
+here = Path(__file__).parent
+
+
+def register_ext_static(app: Sphinx, config: Config):
+    if not hasattr(config, "html_static_path"):
+        config.html_static_path = []
+    config.html_static_path += [str(here / "_static")]
+
+
+def register_highlightjs(app: Sphinx):
+    """Append static contents to highlight by highlight.js."""
+    app.builder.add_css_file("https://cdn.jsdelivr.net/gh/highlightjs/[email protected]/build/styles/default.min.css")
+    app.builder.add_css_file("highlight.css")
+    app.builder.add_js_file("https://cdn.jsdelivr.net/gh/highlightjs/[email protected]/build/highlight.min.js")
+    app.builder.add_js_file("highlight.js")
+
+
+def visit_literal_block(self: SphinxTranslator, node: nodes.literal_block):
+    lang = node["language"]
+    self.body.append(f'<pre><code class="language-{lang}">')
+
+
+def depart_literal_block(self: SphinxTranslator, node: nodes.literal_block):
+    self.body.append("</code></pre>")
+
+
+def setup(app: Sphinx):  # noqa: D103
+    app.connect("config-inited", register_ext_static)
+    app.connect("builder-inited", register_highlightjs)
+    app.add_node(
+        nodes.literal_block,
+        override=True,
+        html=(visit_literal_block, depart_literal_block),
+    )
+    return {
+        "version": __version__,
+        "env_version": 1,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

src/atsphinx/highlightjs/_static/highlight.css

@@ -0,0 +1,6 @@
+/**
+ * Reset pre style for Pygments in Sphinx.
+ */
+pre:has(code) {
+  padding: 0px;
+}

src/atsphinx/highlightjs/_static/highlight.js

@@ -0,0 +1,4 @@
+/**
+ * Affect highlight.js
+ */
+hljs.highlightAll();