Merge pull request #5 from IATI/theme

Initial working version of theme
IATI · Jun 7, 2024 · 0194ff2 · 0194ff2
2 parents 8bb5542 + f23ad1b
commit 0194ff2
Show file tree

Hide file tree

Showing 24 changed files with 396 additions and 62 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,10 @@
 # IATI Sphinx Theme
 
-## Development
+## How do I use IATI Sphinx Theme?
+
+Please see the [IATI Sphinx Theme Documentation](https://iati-sphinx-theme.readthedocs.io/en/latest/) for usage instructions.
+
+## How do I contribute to IATI Sphinx Theme?
 
 ### Install dependencies
 
@@ -38,3 +42,34 @@ mypy iati_sphinx_theme/
    pip install -e .
    sphinx-autobuild -a docs docs/_build/html --watch iati_sphinx_theme/
    ```
+
+### Testing a local version of the theme against another project
+
+To run a local version of the theme with another project, e.g. `my-docs`, take the following steps:
+
+1. Clone the `sphinx-theme` repository, and checkout the branch or tag you want to use.
+
+2. Run the following command in the `sphinx-theme` directory, to build the CSS for the theme.
+
+   ```
+   npm run build
+   ```
+
+3. Go to `my-docs` directory, and install the Sphinx theme
+
+   ```
+   pip install -e /path/to/sphinx-theme
+   ```
+
+4. Set the `html_theme` option in your `conf.py`
+
+   ```python
+   html_theme = "iati_sphinx_theme"
+   ```
+
+5. Start the docs development server:
+
+   ```
+   pip install sphinx-autobuild
+   sphinx-autobuild docs docs/_build/html
+   ```
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,12 +3,9 @@ IATI Sphinx Theme
 =================
 
 .. toctree::
-   :titlesonly:
-   :maxdepth: 2
-   :caption: Usage
    :hidden:
 
-   installation
+   Home <self>
 
 .. toctree::
    :titlesonly:
@@ -17,3 +14,20 @@ IATI Sphinx Theme
    :hidden:
 
    kitchen-sink/index
+
+Installation
+============
+
+1.
+  Install the theme in your Sphinx project.
+
+  .. code-block:: none
+
+    pip install iati-sphinx-theme
+
+2.
+  In your project's :code:`conf.py` set the :code:`html_theme`.
+
+  .. code-block:: python
+
+    html_theme = "iati_sphinx_theme"
diff --git a/docs/installation.rst b/docs/installation.rst
diff --git a/docs/kitchen-sink/api.rst b/docs/kitchen-sink/api.rst
@@ -7,7 +7,7 @@
 API documentation
 *****************
 
-Using Sphinx's :ref:`sphinx.ext.autodoc` plugin, it is possible to auto-generate documentation of a Python module.
+Using Sphinx's :code:`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,

diff --git a/docs/kitchen-sink/generic.rst b/docs/kitchen-sink/generic.rst
@@ -151,6 +151,8 @@ Code with Sidebar
 References
 ==========
 
+.. _footnotes:
+
 Footnotes
 ---------
 
@@ -173,7 +175,7 @@ and ``]_``.  This follow the basic pattern in restructured text to use concise
 symbol combinations inside a paragraph that are unlikely to appear in normal text.
 
 There is also simple markup to do hyperlinks, both to web URL's and as
-cross references within a Sphinx document, like to :ref:`transformation`.
+cross references within a Sphinx document, like to :ref:`footnotes`.
 
 More elaborate documents by some of the authors are
 http://introcs.cs.luc.edu and

diff --git a/docs/kitchen-sink/lists.rst b/docs/kitchen-sink/lists.rst
@@ -18,11 +18,18 @@ Enumerated Lists
    a. nested lists are numbered separately
    b. nested lists need a blank line before and after
 
+      A. Upper Alpha
+
 5. Roman numerals can also be used
 
    i. nested lists are numbered separately
    ii. nested lists need a blank line before and after
 
+6. Upper Roman
+
+   I. first item
+   II. second item
+
 #. Can have automatic number with the ``#`` character.
 
 Definition Lists

diff --git a/iati_sphinx_theme/__init__.py b/iati_sphinx_theme/__init__.py
@@ -7,3 +7,4 @@
 
 def setup(app: sphinx.application.Sphinx) -> None:
     app.add_html_theme("iati_sphinx_theme", path.abspath(path.dirname(__file__)))
+    app.config["html_permalinks_icon"] = "#"
diff --git a/iati_sphinx_theme/globaltoc.html b/iati_sphinx_theme/globaltoc.html
@@ -0,0 +1,3 @@
+<div class="globaltoc">
+  {{ toctree(includehidden=theme_globaltoc_includehidden, collapse=theme_globaltoc_collapse, maxdepth=theme_globaltoc_maxdepth) }}
+</div>
diff --git a/iati_sphinx_theme/layout.html b/iati_sphinx_theme/layout.html
@@ -0,0 +1,87 @@
+{% extends "basic/layout.html" %}
+
+{%- block header %}
+  <div class="iati-title-bar">
+    <header class="iati-header">
+      <div>
+        <a href="https://iatistandard.org/">
+          <img
+            src="http://styles.iatistandard.org/assets/svg/source/logo-colour.svg"
+            class="iati-header__logo"
+          />
+        </a>
+      </div>
+      <ul class="iati-header__nav">
+        <li class="iati-header__nav-item">
+          <a href="{{ pathto('search') }}">Search</a>
+        </li>
+      </ul>
+    </header>
+    <div class="iati-title-bar__title">
+      {{ _(project) }}
+    </div>
+  </div>
+{% endblock %}
+
+{%- block relbar1 %}{% endblock %}
+{%- block relbar2 %}{% endblock %}
+{%- block sidebar1 %}{% endblock %}
+{%- block sidebar2 %}{% endblock %}
+
+{%- block content %}
+  <main class="iati-main">
+    {%- include "globaltoc.html" %}
+    {{ super() }}
+  </main>
+{% endblock %}
+
+{%- block document %}
+  {{ super() }}
+  {%- if theme_show_relations|tobool %}
+    {%- include "relations.html" %}
+  {%- endif %}
+{% endblock %}
+
+{%- block footer %}
+  <footer class="iati-footer" role="contentinfo">
+    <div>
+      <a href="https://iatistandard.org/">
+        <img
+          src="http://styles.iatistandard.org/assets/svg/source/logo-white.svg"
+          class="iati-footer__logo"
+        />
+      </a>
+      <div class="iati-footer__list">
+          <span class="iati-footer__list-title">Useful Links</span>
+          <ul>
+            <li><a href="https://iatistandard.org/en/contact/">Contact</a></li>
+            <li><a href="https://iatistandard.org/en/privacy-policy/">Privacy Policy</a></li>
+          </ul>
+        </div>
+    </div>
+    <hr />
+    <div>
+      <div>
+        {{- copyright_block() -}}
+        Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.
+      </div>
+      <div class="iati-footer__social-icons">
+        <a href="https://twitter.com/IATI_aid" aria-label="Twitter">
+          <i class="iati-icon iati-icon--twitter"></i>
+        </a>
+        <a
+          href="https://www.youtube.com/channel/UCAVH1gcgJXElsj8ENC-bDQQ"
+          aria-label="YouTube"
+        >
+          <i class="iati-icon iati-icon--youtube"></i>
+        </a>
+        <a
+          href="https://www.linkedin.com/company/international-aid-transparency-initiative/"
+          aria-label="LinkedIn"
+        >
+          <i class="iati-icon iati-icon--linkedin"></i>
+        </a>
+      </div>
+    </div>
+  </footer>
+{%- endblock %}
diff --git a/iati_sphinx_theme/relations.html b/iati_sphinx_theme/relations.html
@@ -0,0 +1,18 @@
+<div class="relations">
+  {%- if prev %}
+    <div>
+      <p class="relations__label">Previous</p>
+      <a href="{{ prev.link|e }}">
+        {{ prev.title }}
+      </a>
+    </div>
+  {%- endif %}
+  {%- if next %}
+    <div class="right">
+      <p class="relations__label">Next</p>
+      <a href="{{ next.link|e }}">
+        {{ next.title }}
+      </a>
+    </div>
+  {%- endif %}
+</div>
diff --git a/iati_sphinx_theme/search.html b/iati_sphinx_theme/search.html
@@ -0,0 +1,17 @@
+{% extends "basic/search.html" %}
+
+{% block searchbox %}
+  <form action="" method="get" class="iati-search-bar">
+    <input
+      type="text"
+      name="q"
+      aria-labelledby="search-documentation"
+      value=""
+      autocomplete="off"
+      autocorrect="off"
+      autocapitalize="off"
+      spellcheck="false"
+    />
+    <button type="submit" class="iati-button">Search</button>
+  </form>
+{% endblock %}
diff --git a/iati_sphinx_theme/theme.conf b/iati_sphinx_theme/theme.conf
@@ -2,3 +2,7 @@
 inherit = basic
 stylesheet = iati.css
 pygments_style = default
+
+[options]
+globaltoc_maxdepth = 2
+show_relations = False
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -7,7 +7,7 @@
   "devDependencies": {
     "@commitlint/cli": "^19.3.0",
     "@commitlint/config-conventional": "^19.2.2",
-    "iati-design-system": "1.0.0",
+    "iati-design-system": "^1.2.0",
     "sass": "^1.75.0",
     "semantic-release": "^23.1.1",
     "semantic-release-pypi": "^3.0.0"

diff --git a/styles/_admonitions.scss b/styles/_admonitions.scss
@@ -6,32 +6,23 @@
 .versionchanged,
 div.deprecated {
   @extend .iati-callout;
-}
 
-.admonition-title,
-.topic-title {
-  @extend .iati-callout__title;
-}
+  &.attention {
+    @extend .iati-callout--purple;
+  }
 
-.attention,
-.caution,
-.warning,
-.versionchanged {
-  @extend .iati-callout--orange;
-}
+  &.caution {
+    @extend .iati-callout--orange;
+  }
 
-.danger,
-.error,
-div.deprecated {
-  @extend .iati-callout--red;
-}
-
-.versionadded {
-  @extend .iati-callout--green;
-}
+  &.note {
+    @extend .iati-callout--green;
+  }
 
-.tip {
-  @extend .iati-callout--purple;
+  .admonition-title,
+  .topic-title {
+    @extend .iati-callout__title;
+  }
 }
 
 .versionmodified {

diff --git a/styles/_footnotes.scss b/styles/_footnotes.scss
@@ -0,0 +1,16 @@
+@use "pkg:iati-design-system" as *;
+
+aside.footnote-list {
+  font-size: 0.9em;
+}
+
+aside.footnote {
+  display: flex;
+  flex-flow: row nowrap;
+  align-items: flex-start;
+
+  & > * {
+    margin: 0.2em;
+    line-height: $line-height-body;
+  }
+}