From 8432fdb1f27c0abe68071a8e3b01c8bc6bf4e278 Mon Sep 17 00:00:00 2001
From: Kazuya Takei <myself@attakei.net>
Date: Sat, 21 Oct 2023 20:57:54 +0900
Subject: [PATCH] feat: Render code block for highlight.js

---
 CHANGES.rst                                   |  6 +--
 README.rst                                    | 19 ++++++-
 docs/conf.py                                  |  4 +-
 docs/index.rst                                | 28 +++++++++--
 src/atsphinx/highlightjs.py                   | 13 -----
 src/atsphinx/highlightjs/__init__.py          | 49 +++++++++++++++++++
 .../highlightjs/_static/highlight.css         |  6 +++
 src/atsphinx/highlightjs/_static/highlight.js |  4 ++
 8 files changed, 107 insertions(+), 22 deletions(-)
 delete mode 100644 src/atsphinx/highlightjs.py
 create mode 100644 src/atsphinx/highlightjs/__init__.py
 create mode 100644 src/atsphinx/highlightjs/_static/highlight.css
 create mode 100644 src/atsphinx/highlightjs/_static/highlight.js

diff --git a/CHANGES.rst b/CHANGES.rst
index 29ab530..00ecdf7 100644
--- a/CHANGES.rst
+++ b/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.
diff --git a/README.rst b/README.rst
index 0ef21fa..ae20492 100644
--- a/README.rst
+++ b/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>`_.
diff --git a/docs/conf.py b/docs/conf.py
index 632f182..b29999b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -9,7 +9,7 @@
 
 # -- General configuration
 extensions = [
-    "sphinx.ext.todo",
+    "atsphinx.highlightjs",
 ]
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
@@ -17,3 +17,5 @@
 # -- Options for HTML output
 html_theme = "alabaster"
 html_static_path = ["_static"]
+
+# -- Options for extensions
diff --git a/docs/index.rst b/docs/index.rst
index cf24a8f..de9568a 100644
--- a/docs/index.rst
+++ b/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.
diff --git a/src/atsphinx/highlightjs.py b/src/atsphinx/highlightjs.py
deleted file mode 100644
index 7f5d12c..0000000
--- a/src/atsphinx/highlightjs.py
+++ /dev/null
@@ -1,13 +0,0 @@
-"""Override code-block output for highlight.js"""
-from sphinx.application import Sphinx
-
-__version__ = "0.0.0"
-
-
-def setup(app: Sphinx):  # noqa: D103
-    return {
-        "version": __version__,
-        "env_version": 1,
-        "parallel_read_safe": True,
-        "parallel_write_safe": True,
-    }
diff --git a/src/atsphinx/highlightjs/__init__.py b/src/atsphinx/highlightjs/__init__.py
new file mode 100644
index 0000000..5911327
--- /dev/null
+++ b/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/cdn-release@11.9.0/build/styles/default.min.css")
+    app.builder.add_css_file("highlight.css")
+    app.builder.add_js_file("https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/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,
+    }
diff --git a/src/atsphinx/highlightjs/_static/highlight.css b/src/atsphinx/highlightjs/_static/highlight.css
new file mode 100644
index 0000000..35eb5ea
--- /dev/null
+++ b/src/atsphinx/highlightjs/_static/highlight.css
@@ -0,0 +1,6 @@
+/**
+ * Reset pre style for Pygments in Sphinx.
+ */
+pre:has(code) {
+  padding: 0px;
+}
diff --git a/src/atsphinx/highlightjs/_static/highlight.js b/src/atsphinx/highlightjs/_static/highlight.js
new file mode 100644
index 0000000..bc7be99
--- /dev/null
+++ b/src/atsphinx/highlightjs/_static/highlight.js
@@ -0,0 +1,4 @@
+/**
+ * Affect highlight.js
+ */
+hljs.highlightAll();