Initial scaffolding for the docs

Author: jimmac

.gitignore

@@ -0,0 +1,4 @@
+build
+.vscode
+_build/
+__pycache__

.gitlab-ci.yml

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2021 GNOME Foundation
+#
+# SPDX-License-Identifier: CC0-1.0
+
+stages:
+ - check
+ - deploy
+
+image: fedora:39
+
+build:
+  stage: check
+  needs: []
+  script:
+    - dnf install -y python3-pip
+    - pip3 install --upgrade -r requirements.txt
+    - sphinx-build -b html source build
+    - mv build/_static/404.html build/404.html
+    - mkdir _docs
+    - mv build/* _docs/
+  artifacts:
+    paths:
+      - _docs
+
+pages:
+  stage: deploy
+  needs: ['build']
+  script:
+    - mv _docs public
+  artifacts:
+    paths:
+      - public
+  only:
+    - main
+

00localbuild.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+rm -rf ./build && sphinx-build -j auto -b html ./source ./build

COPYING.md

@@ -0,0 +1,25 @@
+## Per-file attritubion
+
+Allan Day, Calum Benson, Adam Elman, Seth Nickell, Colin Robertson:
+
+* buttons.rst
+* check-boxes.rst:
+* dialogs.rst
+* keyboard-interaction.rst
+* menus.rst
+* radio-buttons.rst
+* sliders.rst
+* spin-buttons.rst
+* text-fields.rst
+* progress-bars.rst
+* tabs.rst
+* model-based.rst
+* drop-downs.rst
+
+Allan Day, William Jon McCann:
+
+* typography.rst
+
+Allan Day, Calum Benson, Adam Elman, Seth Nickell, Colin Robertson, Ekaterina Gerasimova:
+
+* writing-style.rst

Makefile

@@ -0,0 +1,12 @@
+all:
+	sphinx-build -b html -j auto source build
+
+clean:
+	rm -rf build
+
+run:
+	epiphany build/index.html || firefox build/index.html
+
+install:
+
+

README.md

@@ -0,0 +1,50 @@
+# Human Interface Guidelines
+
+The GNOME Human Interface Guidelines are the primary source of UX design documentation for GNOME. Live at [developer.gnome.org/hig](https://developer.gnome.org/hig).
+
+This version replaces the previous version which was hosted as part of the [gnome-devel-docs](https://gitlab.gnome.org/GNOME/gnome-devel-docs/) module.
+
+The HIG is written in [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), generated using [Sphinx](https://www.sphinx-doc.org/en/master/index.html), and hosted using [GitLab pages](https://docs.gitlab.com/ee/user/project/pages/). It can be viewed online [here](https://developer.gnome.org/hig/).
+
+## Goals for the HIG
+
+Goals:
+
+ - App designers and developers are the primary audiences
+ - Document the most important and commond design patterns
+ - Be easy to digest: don't be too long or verbose
+ - Use examples and demos as much as possible 
+
+Non-goals:
+
+ - Not a generic guide to UX design, and shouldn't try to fill in basic design knowledge, but should be accessible to those with relatively little design expertise
+ - Don't document every design pattern or possible variation
+ - Don't be prescriptive: allow designers to make their own choices, and give them the space to be creative
+
+## How to build and edit
+
+Sphinx can be used to build and preview the static html site locally, either with the browser or VS Code.
+
+### 1. Install dependencies
+
+On Fedora, run:
+
+```
+dnf install -y python3-sphinx python3-pip
+pip3 install --upgrade furo
+```
+
+### 2. Make changes
+
+VS Code is a good choice for this, as it is able to preview the source files as rendered HTML.
+
+### 3. Build
+
+Building the docs checks for errors, as well as producing local static HTML of the HIG website.
+
+To build, run `00localbuild.sh` from the project root. The build output can then be found in ``/build``.
+
+### 4. Deploy changes
+
+Changes to `main` branch are automatically deployed to the site using CI.
+

requirements.in

@@ -0,0 +1,2 @@
+sphinx==6.2.*
+furo

requirements.txt

@@ -0,0 +1,61 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile requirements.in
+#
+alabaster==0.7.16
+    # via sphinx
+babel==2.14.0
+    # via sphinx
+beautifulsoup4==4.12.3
+    # via furo
+certifi==2023.11.17
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+docutils==0.19
+    # via sphinx
+furo==2024.1.29
+    # via -r requirements.in
+idna==3.6
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.3
+    # via sphinx
+markupsafe==2.1.4
+    # via jinja2
+packaging==23.2
+    # via sphinx
+pygments==2.17.2
+    # via
+    #   furo
+    #   sphinx
+requests==2.31.0
+    # via sphinx
+snowballstemmer==2.2.0
+    # via sphinx
+soupsieve==2.5
+    # via beautifulsoup4
+sphinx==6.2.1
+    # via
+    #   -r requirements.in
+    #   furo
+    #   sphinx-basic-ng
+sphinx-basic-ng==1.0.0b2
+    # via furo
+sphinxcontrib-applehelp==1.0.8
+    # via sphinx
+sphinxcontrib-devhelp==1.0.6
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.5
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.7
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.10
+    # via sphinx
+urllib3==2.1.0
+    # via requests

source/_ext/hig_palette.py

@@ -0,0 +1,107 @@
+"""
+    hig_www.hig_palette
+    ~~~~~~~~~~~~~~~~~~~
+
+    Access properties of GNOME's HIG palette via rST roles.
+"""
+
+from urllib.parse import urljoin
+import base64
+
+from docutils.utils import unescape
+from docutils import nodes
+from sphinx.errors import ExtensionError
+
+# Name of this extension
+extname = "hig_palette"
+# The variable in conf.py that maps color names to (R, G, B) tuples
+colors_var = "hig_palette_colors_rgb"
+# This can be used within the CSS to apply styles to the resulting image
+svg_class_name = "hig-palette-swatch"
+
+"""
+Creates an SVG containing a rect, filled with the RGB tuple passed in.
+"""
+def create_palette_svg_str(rgb):
+    return """
+    <svg width="100%%" height="100%%"
+        xmlns="http://www.w3.org/2000/svg"
+        xmlns:xlink="http://www.w3.org/1999/xlink">
+
+    <rect width="100%%" height="100%%" fill="rgb%s" />
+    </svg>
+    """ % rgb.__str__()
+
+def create_rgb_node(rgb):
+    output = rgb.__str__()
+    return nodes.Text(output, output)
+
+def create_hex_node(rgb):
+    red, green, blue = rgb
+    output = f"#{red:02x}{green:02x}{blue:02x}"
+    return nodes.Text(output, output)
+
+def create_svg_node(rgb, name):
+    svg_str = create_palette_svg_str(rgb)
+    svg_base64_str = base64.b64encode(svg_str.encode("ascii"))
+    uri = f"data:image/svg+xml;base64,{svg_base64_str.decode('ascii')}"
+
+    node = nodes.image(svg_str)
+    node["uri"] = uri
+
+    node['classes'].append(svg_class_name)
+    node["alt"] = f"Color '{name}' from the GNOME HIG palette"
+
+    return node
+
+"""
+Creates a role function that can be registered with Sphinx.
+"""
+def make_palette_role(color_mappings, representation):
+    valid_representations = ["rgb", "hex", "svg"]
+
+    if not representation in valid_representations:
+        raise ExtensionError("Cannot generate representation '%s' for colors"
+            % representation, modname=extname)
+
+    def role(type, rawtext, text, lineno, inliner, options={}, content={}):
+        color_name = unescape(text)
+
+        if not color_name in color_mappings:
+            raise ExtensionError(
+                "Definition for color '%s' not found in conf.py" % color_name,
+                modname=extname)
+
+        color_rgb = color_mappings[color_name]
+        node = None
+
+        if representation == "rgb":
+            node = create_rgb_node(color_rgb)
+        elif representation == "hex":
+            node = create_hex_node(color_rgb)
+        elif representation == "svg":
+            node = create_svg_node(color_rgb, color_name)
+
+        return [node], []
+
+    return role
+
+def setup_palette_roles(app):
+    color_mappings = app.config[colors_var]
+
+    # returns a text node with a tuple (R, G, B) representing a defined color
+    app.add_role("palette-rgb", make_palette_role(color_mappings, "rgb"))
+    # returns a text node with the hexadecimal representation of a defined color
+    app.add_role("palette-hex", make_palette_role(color_mappings, "hex"))
+    # returns an image node set to an SVG from create_palette_svg()
+    app.add_role("palette-svg", make_palette_role(color_mappings, "svg"))
+
+def setup(app):
+    app.add_config_value(colors_var, {}, "env")
+    app.connect("builder-inited", setup_palette_roles)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parellel_write_safe": True
+    }