Merge branch 'init/sass'

.gitignore

@@ -1,5 +1,5 @@
-### GIGI version 0.1.0
-### command with: python
+### GIGI version 0.2.1
+### command with: python node
 
 ### Python ###
 # Byte-compiled / optimized / DLL files
@@ -172,3 +172,145 @@ poetry.toml
 
 # LSP config files
 pyrightconfig.json
+
+### Node ###
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+### Node Patch ###
+# Serverless Webpack directories
+.webpack/
+
+# Optional stylelint cache
+.stylelintcache
+
+# SvelteKit build / generate output
+.svelte-kit

docs/_sass/demo.scss

@@ -0,0 +1,7 @@
+@use "bulma/sass/utilities/extends";
+
+.sass-demo-bulma-content {
+  @extend %control;
+  background-color: purple;
+  color: white;
+}

docs/conf.py

@@ -1,6 +1,10 @@
+from pathlib import Path
+
 from atsphinx.mini18n import get_template_dir as get_mini18n_template_dir
 from atsphinx.toybox import __version__ as version
 
+root = Path(__file__).parent
+
 # -- Project information
 project = "atsphinx-toybox"
 copyright = "2024, Kazuya Takei"
@@ -16,10 +20,11 @@
     # Third-party extensions
     "atsphinx.mini18n",
     # My extensions
+    "atsphinx.toybox.sass",
     "atsphinx.toybox.stlite",
 ]
 templates_path = ["_templates", get_mini18n_template_dir()]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "node_modules"]
 
 # -- Options for i18n
 gettext_compact = False
@@ -33,6 +38,7 @@
     "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/fontawesome.min.css",
     "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/solid.min.css",
     "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/brands.min.css",
+    "css/demo.css",
 ]
 html_theme_options = {
     "footer_icons": [
@@ -67,6 +73,9 @@
 mini18n_default_language = "en"
 mini18n_support_languages = ["en", "ja"]
 mini18n_basepath = "/toybox/"
+# atsphinx.toybox.sass
+sass_load_paths = [root / "node_modules"]
+sass_extra_options = ["--update", "-q"]
 
 
 def setup(app):

docs/extensions/sass/index.rst

@@ -0,0 +1,57 @@
+====================
+atsphinx.toybox.sass
+====================
+
+Overview
+========
+
+This compiles SASS/SCSS resources into css when run sphinx-build.
+This it to embed Stlite content into your documents.
+
+Usage
+=====
+
+Enable extension
+----------------
+
+Add this into your ``conf.py`` of Sphinx.
+
+.. code-block:: python
+   :caption: conf.py
+
+   extensions = [
+       "atsphinx.toybox.sass",
+   ]
+
+Configuration
+-------------
+
+There are not configuration options.
+
+.. note:: I will add some optioons.
+
+Demo
+====
+
+This content is used generated CSS from SASS.
+
+.. code:: rst
+
+   .. container:: sass-demo-bulma-content
+
+      This paragraph is colored by "purplel".
+
+.. literalinclude:: ../../_sass/demo.scss
+   :caption: docs/_sass/demo.scss
+
+Result:
+
+.. container:: sass-demo-bulma-content
+
+   This paragraph is colored by "purplel".
+
+Refs
+====
+
+* `dart-sacc CLI <https://sass-lang.com/documentation/cli/dart-sass/>`_
+* `Repository <https://github.com/sass/dart-sass/>`_

docs/package.json

@@ -0,0 +1,15 @@
+{
+	"name": "docs",
+	"version": "2024.12.2",
+	"description": "",
+	"main": "index.js",
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "Apache-2.0",
+	"dependencies": {
+		"bulma": "^1.0.2"
+	}
+}

pyproject.toml

@@ -38,6 +38,11 @@ dependencies = [
 Home = "https://github.com/atsphinx/toybox"
 Documentation = "https://atsphinx.github.io/toybox"
 
+[project.optional-dependencies]
+sass = [
+    "httpx>=0.28.0",
+]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

src/atsphinx/toybox/sass/.gitignore

@@ -0,0 +1 @@
+_bin

src/atsphinx/toybox/sass/__init__.py

@@ -0,0 +1,66 @@
+"""Sass autobuild.
+
+Spec
+====
+
+* Use dart-sass binary
+* Auto find ``_sass`` directory.
+* Exclude ``_`` prefixed files.
+* Copy into _static
+* Timestamp based incremental build.
+"""
+
+import subprocess
+from pathlib import Path
+
+from sphinx.application import Sphinx
+from sphinx.config import Config
+
+from . import dart_sass
+
+SASS_VERSION = "1.81.0"
+
+package_root = Path(__file__).parent
+
+bin_dist = package_root / "_bin"
+sass_bin: Path
+
+
+def configure_sass_bin(app: Sphinx, config: Config):
+    """Set up sass executable. It download binary if it needs."""
+    global sass_bin
+    sass_bin = dart_sass.setup_dart_sass(SASS_VERSION, bin_dist)
+
+
+def compile_assets(app: Sphinx):
+    """Compile assets (sass or scss to css)."""
+    global sass_bin
+    source_dir = app.srcdir / "_sass"
+    output_dir = app.srcdir / "_static" / "css"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    options = []
+    if app.config.sass_load_paths:
+        options += [f"--load-path={p}" for p in app.config.sass_load_paths]
+    options += app.config.sass_extra_options
+    cmd = [str(sass_bin), *options, f"{source_dir}:{output_dir}"]
+    subprocess.run(cmd)
+
+
+def setup(app: Sphinx):  # noqa: D103
+    app.add_config_value(
+        "sass_load_paths",
+        [],
+        "env",
+        list[str],
+        "Path list of external import resources",
+    )
+    app.add_config_value(
+        "sass_extra_options",
+        [],
+        "env",
+        list[str],
+        "Option arguments of dart-sass",
+    )
+    app.connect("config-inited", configure_sass_bin)
+    app.connect("builder-inited", compile_assets)
+    return {}