Merge pull request #1 from IATI/setup

Set up project

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+on: [push]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+    - name: Install dev requirements
+      run: pip install -r requirements_dev.txt
+    - name: Check black
+      run: black --check iati_sphinx_theme
+    - name: Check isort
+      run: isort --check-only iati_sphinx_theme
+    - name: Check flake8
+      run: flake8 iati_sphinx_theme

.gitignore

@@ -0,0 +1,4 @@
+# Python
+.ve
+__pycache__
+dist

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+sphinx:
+  configuration: docs/conf.py
+  builder: dirhtml
+
+python:
+  install:
+    - method: pip
+      path: .

README.md

@@ -1 +1,34 @@
-# sphinx-theme
+# IATI Sphinx Theme
+
+## 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
+```
+
+### Run linting
+
+```
+black iati_sphinx_theme
+isort iati_sphinx_theme
+flake8 iati_sphinx_theme
+```
+
+### Documentation with live preview
+
+1. Install the theme locally:
+    ```
+    pip install -e .
+    ```
+
+2. Start the docs development server:
+    ```
+    sphinx-autobuild docs docs/_build/html
+    ```

docs/.gitignore

@@ -0,0 +1 @@
+_build

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,29 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "IATI Sphinx Theme"
+copyright = "2024 IATI Secretariat"
+author = "IATI Secretariat"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.todo",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "iati_sphinx_theme"
+html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,10 @@
+=================
+IATI Sphinx Theme
+=================
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 2
+   :caption: Table of Contents
+
+   kitchen-sink/index

docs/kitchen-sink/admonitions.rst

@@ -0,0 +1,123 @@
+..
+   Copyright (c) 2021 Pradyun Gedam
+   Licensed under Creative Commons Attribution-ShareAlike 4.0 International License
+   SPDX-License-Identifier: CC-BY-SA-4.0
+
+===========
+Admonitions
+===========
+
+Sphinx provides several different types of admonitions.
+
+``topic``
+=========
+
+.. topic:: This is a topic.
+
+   This is what admonitions are a special case of, according to the docutils
+   documentation.
+
+``admonition``
+==============
+
+.. admonition:: The one with the custom titles
+
+   It's got a certain charm to it.
+
+``attention``
+=============
+
+.. attention::
+
+   Climate change is real.
+
+``caution``
+===========
+
+.. caution::
+
+   Cliff ahead: Don't drive off it.
+
+``danger``
+==========
+
+.. danger::
+
+   Mad scientist at work!
+
+``error``
+=========
+
+.. error::
+
+   Does not compute.
+
+``hint``
+========
+
+.. hint::
+
+   Insulators insulate, until they are subject to ______ voltage.
+
+``important``
+=============
+
+.. important::
+
+   Tech is not neutral, nor is it apolitical.
+
+``note``
+========
+
+.. note::
+
+   This is a note.
+
+``seealso``
+===========
+
+.. seealso::
+
+   Other relevant information.
+
+``tip``
+=======
+
+.. tip::
+
+   25% if the service is good.
+
+``todo``
+========
+
+.. todo::
+
+   This needs the ``sphinx.ext.todo`` extension.
+
+``warning``
+===========
+
+.. warning::
+
+   Reader discretion is strongly advised.
+
+``versionadded``
+================
+
+.. versionadded:: v0.1.1
+
+   Here's a version added message.
+
+``versionchanged``
+==================
+
+.. versionchanged:: v0.1.1
+
+   Here's a version changed message.
+
+``deprecated``
+==============
+
+.. deprecated:: v0.1.1
+
+   Here's a deprecation message.

docs/kitchen-sink/api.rst

@@ -0,0 +1,29 @@
+..
+   Copyright (c) 2021 Pradyun Gedam
+   Licensed under Creative Commons Attribution-ShareAlike 4.0 International License
+   SPDX-License-Identifier: CC-BY-SA-4.0
+
+*****************
+API documentation
+*****************
+
+Using Sphinx's :ref:`sphinx.ext.autodoc` plugin, it is possible to auto-generate documentation of a Python module.
+
+.. tip::
+    Avoid having in-function-signature type annotations with autodoc,
+    by setting the following options:
+
+    .. code-block:: python
+
+        # -- Options for autodoc ----------------------------------------------------
+        # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
+
+        # Automatically extract typehints when specified and place them in
+        # descriptions of the relevant function/method.
+        autodoc_typehints = "description"
+
+        # Don't show class signature with the class' name.
+        autodoc_class_signature = "separated"
+
+.. automodule:: urllib.request
+    :members: