Merge pull request #2 from IATI/add-npm

Add IATI design system

.gitignore

@@ -2,3 +2,6 @@
 .ve
 __pycache__
 dist
+
+# Node
+node_modules

.readthedocs.yaml

@@ -7,6 +7,11 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
+    nodejs: "20"
+  jobs:
+    pre_install:
+      - npm ci
+      - npm run build
 
 sphinx:
   configuration: docs/conf.py

README.md

@@ -3,11 +3,13 @@
 ## Development
 
 ### Install dependencies
+
 ```
 pip install -r requirements_dev.txt
 ```
 
 ### Update dependencies
+
 ```
 python -m piptools compile --extra=dev -o requirements_dev.txt pyproject.toml
 pip install -r requirements_dev.txt
@@ -23,12 +25,15 @@ flake8 iati_sphinx_theme
 
 ### Documentation with live preview
 
-1. Install the theme locally:
-    ```
-    pip install -e .
-    ```
+1. In one terminal, build the CSS in watch mode
+
+   ```
+   npm run build:watch
+   ```
+
+2. In a separate terminal, install the Sphinx theme then start the docs development server:
 
-2. Start the docs development server:
-    ```
-    sphinx-autobuild docs docs/_build/html
-    ```
+   ```
+   pip install -e .
+   sphinx-autobuild -a docs docs/_build/html --watch iati_sphinx_theme/
+   ```

docs/conf.py

@@ -26,4 +26,4 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "iati_sphinx_theme"
-html_static_path = ["_static"]
+todo_include_todos = True

docs/kitchen-sink/generic.rst

@@ -152,7 +152,7 @@ References
 ==========
 
 Footnotes
-~~~~~~~~~~~
+---------
 
 Here we have a footnote. [#doubleColon]_
 

iati_sphinx_theme/static/.gitignore

@@ -0,0 +1,2 @@
+# Autogenerated CSS
+iati.css

iati_sphinx_theme/theme.conf

@@ -1,2 +1,4 @@
 [theme]
 inherit = basic
+stylesheet = iati.css
+pygments_style = default

package.json

@@ -0,0 +1,11 @@
+{
+  "name": "sphinx-theme",
+  "scripts": {
+    "build": "sass --pkg-importer=node --style=expanded --no-source-map styles/main.scss:iati_sphinx_theme/static/iati.css",
+    "build:watch": "npm run build -- --watch"
+  },
+  "devDependencies": {
+    "iati-design-system": "1.0.0",
+    "sass": "^1.75.0"
+  }
+}

styles/_admonitions.scss

@@ -0,0 +1,39 @@
+@use "pkg:iati-design-system" as ds;
+
+.admonition,
+.topic,
+.versionadded,
+.versionchanged,
+div.deprecated {
+  @extend .iati-callout;
+}
+
+.admonition-title,
+.topic-title {
+  @extend .iati-callout__title;
+}
+
+.attention,
+.caution,
+.warning,
+.versionchanged {
+  @extend .iati-callout--orange;
+}
+
+.danger,
+.error,
+div.deprecated {
+  @extend .iati-callout--red;
+}
+
+.versionadded {
+  @extend .iati-callout--green;
+}
+
+.tip {
+  @extend .iati-callout--purple;
+}
+
+.versionmodified {
+  font-weight: bold;
+}