diff --git a/README.md b/README.md index 89bd668..2fd1d2a 100644 --- 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 index d28010c..f760c6f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,12 +3,9 @@ IATI Sphinx Theme ================= .. toctree:: - :titlesonly: - :maxdepth: 2 - :caption: Usage :hidden: - installation + Home .. 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 deleted file mode 100644 index 4aa48f8..0000000 --- a/docs/installation.rst +++ /dev/null @@ -1,17 +0,0 @@ -============ -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/kitchen-sink/api.rst b/docs/kitchen-sink/api.rst index dc280a0..2a49ea4 100644 --- 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 index e90f1f9..8596e12 100644 --- 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 index 7e698d6..1d7bec0 100644 --- 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 index 2bfaa64..ee828d1 100644 --- 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 new file mode 100644 index 0000000..bfb8b1a --- /dev/null +++ b/iati_sphinx_theme/globaltoc.html @@ -0,0 +1,3 @@ +
+ {{ toctree(includehidden=theme_globaltoc_includehidden, collapse=theme_globaltoc_collapse, maxdepth=theme_globaltoc_maxdepth) }} +
diff --git a/iati_sphinx_theme/layout.html b/iati_sphinx_theme/layout.html new file mode 100644 index 0000000..95ed361 --- /dev/null +++ b/iati_sphinx_theme/layout.html @@ -0,0 +1,87 @@ +{% extends "basic/layout.html" %} + +{%- block header %} +
+
+
+ + + +
+ +
+
+ {{ _(project) }} +
+
+{% endblock %} + +{%- block relbar1 %}{% endblock %} +{%- block relbar2 %}{% endblock %} +{%- block sidebar1 %}{% endblock %} +{%- block sidebar2 %}{% endblock %} + +{%- block content %} +
+ {%- include "globaltoc.html" %} + {{ super() }} +
+{% endblock %} + +{%- block document %} + {{ super() }} + {%- if theme_show_relations|tobool %} + {%- include "relations.html" %} + {%- endif %} +{% endblock %} + +{%- block footer %} + +{%- endblock %} diff --git a/iati_sphinx_theme/relations.html b/iati_sphinx_theme/relations.html new file mode 100644 index 0000000..0975e83 --- /dev/null +++ b/iati_sphinx_theme/relations.html @@ -0,0 +1,18 @@ +
+ {%- if prev %} +
+

Previous

+ + {{ prev.title }} + +
+ {%- endif %} + {%- if next %} +
+

Next

+ + {{ next.title }} + +
+ {%- endif %} +
diff --git a/iati_sphinx_theme/search.html b/iati_sphinx_theme/search.html new file mode 100644 index 0000000..f5ef42d --- /dev/null +++ b/iati_sphinx_theme/search.html @@ -0,0 +1,17 @@ +{% extends "basic/search.html" %} + +{% block searchbox %} +
+ + +
+{% endblock %} diff --git a/iati_sphinx_theme/theme.conf b/iati_sphinx_theme/theme.conf index f07175d..c8cd002 100644 --- 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 index f98608f..68f0350 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8,7 +8,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" @@ -2927,9 +2927,9 @@ } }, "node_modules/iati-design-system": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/iati-design-system/-/iati-design-system-1.0.0.tgz", - "integrity": "sha512-vp/Hp6PQSSZdlIBw7YM41/NKBu0bHL4hVEVWkLUdPzOJY2h3ANdpy9yZ7WDLRLB/pa7k+Nmat+LuFl3svezICA==", + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/iati-design-system/-/iati-design-system-1.2.0.tgz", + "integrity": "sha512-67GZAQ8FcYRJyF7CWDDeSbKAlHmqxkzAxoCesMIZzFIhU+fyy/U4K2ItqGqgsE9ks9ANphiNFAN2SmLqPtxYjA==", "dev": true, "dependencies": { "normalize-scss": "^8.0.0" diff --git a/package.json b/package.json index 95f8e97..55c2c93 100644 --- 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 index 1037a41..c622e9c 100644 --- 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 new file mode 100644 index 0000000..dc9b418 --- /dev/null +++ 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; + } +} diff --git a/styles/_globaltoc.scss b/styles/_globaltoc.scss new file mode 100644 index 0000000..735b721 --- /dev/null +++ b/styles/_globaltoc.scss @@ -0,0 +1,27 @@ +@use "pkg:iati-design-system" as *; + +.globaltoc { + @extend .iati-card; + margin: $padding-block; + + @media (min-width: $screen-lg) { + flex: 0 0 250px; + align-self: flex-start; + } + + & .caption { + @extend .iati-card__subtitle; + + .caption-text { + font-style: normal; + } + + &:not(:first-of-type) { + margin-top: $padding-block; + } + } + + ul { + @extend .iati-card__menu; + } +} diff --git a/styles/_layout.scss b/styles/_layout.scss new file mode 100644 index 0000000..0ac7a25 --- /dev/null +++ b/styles/_layout.scss @@ -0,0 +1,23 @@ +@use "pkg:iati-design-system" as *; + +.iati-main { + display: flex; + padding: 0; + flex-direction: column; + + @media (min-width: $screen-lg) { + flex-direction: row; + } +} + +.document { + flex-grow: 1; + display: flex; + flex-flow: column nowrap; + overflow: auto; +} + +.documentwrapper { + flex-grow: 1; + padding: $padding-block; +} diff --git a/styles/_relations.scss b/styles/_relations.scss new file mode 100644 index 0000000..bde485d --- /dev/null +++ b/styles/_relations.scss @@ -0,0 +1,16 @@ +@use "pkg:iati-design-system" as *; + +.relations { + display: flex; + padding: $padding-block; + + & > * { + flex: 1; + } + + &__label { + margin: 0; + font-weight: bold; + font-size: 0.9em; + } +} diff --git a/styles/_sidebar.scss b/styles/_sidebar.scss new file mode 100644 index 0000000..6dddab7 --- /dev/null +++ b/styles/_sidebar.scss @@ -0,0 +1,18 @@ +@use "pkg:iati-design-system" as *; + +aside.sidebar { + @extend .iati-card; + float: right; + clear: both; + width: 250px; + overflow: auto; + margin-left: $padding-block; + + & .sidebar-title { + @extend .iati-card__title; + } + + & .sidebar-subtitle { + @extend .iati-card__subtitle; + } +} diff --git a/styles/_tables.scss b/styles/_tables.scss new file mode 100644 index 0000000..41e0ac4 --- /dev/null +++ b/styles/_tables.scss @@ -0,0 +1,7 @@ +@use "pkg:iati-design-system" as *; + +table { + p { + margin: 0; + } +} diff --git a/styles/_typography.scss b/styles/_typography.scss index e0e6f3d..ab7579a 100644 --- a/styles/_typography.scss +++ b/styles/_typography.scss @@ -1,13 +1,5 @@ @use "pkg:iati-design-system" as ds; -.centered { - text-align: center; -} - -.right { - text-align: right; -} - .rubric { font-weight: bold; font-size: 1.2em; @@ -23,9 +15,11 @@ } .headerlink { - color: ds.$color-grey-40; + color: ds.$color-grey-30; text-decoration: none; padding-left: ds.$padding-block; + font-size: 0.8em; + font-weight: ds.$font-weight-body; &:hover { color: ds.$color-grey-90; @@ -35,7 +29,7 @@ .guilabel { background-color: ds.$color-teal-10; border: 1px solid ds.$color-teal-70; - font-size: 0.9em; + font-size: 0.6em; padding: 0 0.2em; border-radius: 0.2em; } @@ -60,7 +54,20 @@ span.linenos { margin-right: ds.$padding-block; } -.code-block-caption { +.highlight { + background: none; +} + +// Captions + +.code-block-caption, +.caption-text { text-align: center; font-style: italic; } + +// Description Lists + +dl dt .classifier::before { + content: " : "; +} diff --git a/styles/_utilities.scss b/styles/_utilities.scss new file mode 100644 index 0000000..d535abf --- /dev/null +++ b/styles/_utilities.scss @@ -0,0 +1,51 @@ +/* Generic utilities which Sphinx expects to be available */ + +@use "pkg:iati-design-system" as *; + +// List Styles + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperroman { + list-style: upper-roman; +} + +ol.lowerroman { + list-style: lower-roman; +} + +// Alignment + +.centered { + text-align: center; +} + +.right { + text-align: right; +} + +.align-right { + float: right; + clear: right; + margin-left: $padding-block; +} + +.align-left { + float: left; + clear: left; + margin-right: $padding-block; +} + +.align-center { + text-align: center; +} + +.align-default { + margin-left: 0; +} diff --git a/styles/main.scss b/styles/main.scss index 7d78a4b..c56a7da 100644 --- a/styles/main.scss +++ b/styles/main.scss @@ -1,3 +1,10 @@ @use "pkg:iati-design-system"; @use "typography"; +@use "layout"; @use "admonitions"; +@use "relations"; +@use "globaltoc"; +@use "sidebar"; +@use "footnotes"; +@use "tables"; +@use "utilities";