Merge pull request #147 from attakei/feature/footnotes

Add optional-extension `sphinx_revealjs.ext.footnotes`

demo/_sections/standard-usage.rst

@@ -58,3 +58,10 @@ If you make docs as Reveal.js presentation, you call ``make revealjs``.
    make revealjs
 
 This presentation is made from `source <https://github.com/attakei/sphinx-revealjs/blob/master/demo/index.rst>`_.
+
+Footnotes
+---------
+
+You can set footnotes. footnotes are rendered on tail of slide by using internal-extension. [#]_
+
+.. [#] This is footnote.

demo/conf.py

@@ -18,6 +18,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.todo",
     "sphinx_revealjs",
+    "sphinx_revealjs.ext.footnotes",
     "sphinx_revealjs.ext.screenshot",
     "sphinxcontrib.budoux",
     "sphinxcontrib.gtagjs",

doc/optional-extensions/footnotes.rst

@@ -0,0 +1,62 @@
+=============================
+sphinx_revealjs.ext.footnotes
+=============================
+
+:Added: v2.8.0
+
+Overview
+========
+
+This extension updates position of footnotes.
+
+Installation
+============
+
+You need not install extra, you can use it immediately after installing |THIS|.
+
+Usage
+=====
+
+WHen adding extension into your ``conf.py``, insert CSS file to customize layout of footnotes.
+
+Example
+-------
+
+.. code-block:: python
+   :caption: conf.py
+
+   extensions = [
+       "sphinx_revealjs",
+       "sphinx_revealjs.ext.footnotes",
+   ]
+
+.. code-block:: rst
+   :caption: sample-slide.rst
+
+   Sample title
+   ============
+
+   This sentence has footnotes [#f1]_
+
+   .. [#f1] This is footnote.
+
+Configuration
+=============
+
+All Configuration names are prefixed ``revealjs_footnotes_``.
+
+.. confval:: revealjs_footnotes_font_size
+
+   :Type: ``str``
+   :Default: ``50%``
+   :Example: ``60%``
+
+   Font-size of rendered footnote contents.
+
+.. confval:: revealjs_footnotes_ref_font_size
+
+   :Type: ``str``
+   :Default: ``70%``
+   :Example: ``60%``
+
+   Font-size of rendered footnote's referer text.

sphinx_revealjs/__init__.py

@@ -71,6 +71,7 @@ def setup(app: Sphinx):
     if python_version not in python_support:
         logger.warning("You are using not supported version Python.")
 
+    app.add_event("revealjs:ready-for-writing")
     app.connect("config-inited", inherit_extension_nodes)
     app.connect("config-inited", convert_reveal_js_files)
     app.connect("config-inited", notify_deprecated)

sphinx_revealjs/builders.py

@@ -1,7 +1,7 @@
 """Definition for sphinx custom builder."""
 import copy
 import logging
-from typing import Any, Dict, List, Tuple
+from typing import Any, Dict, List, Set, Tuple
 
 from sphinx import version_info as sphinx_versoin
 from sphinx.application import Sphinx
@@ -129,6 +129,10 @@ def configure_page_script_conf(self) -> List[str]:  # noqa
             configs.append(self.revealjs_slide.content)
         return configs
 
+    def prepare_writing(self, docnames: Set[str]):
+        super().prepare_writing((docnames))
+        self.events.emit("revealjs:ready-for-writing", self.globalcontext)
+
 
 class DirectoryRevealjsHTMLBuilder(DirectoryHTMLBuilder, RevealjsHTMLBuilder):
     """Custom RevealjsHTMLBuilder to generate all HTML pages as ``index.html``.

sphinx_revealjs/ext/footnotes/__init__.py

@@ -0,0 +1,43 @@
+"""Extension to add custom CSS for footnotes."""
+from pathlib import Path
+
+from sphinx.application import Sphinx
+from sphinx.util.logging import getLogger
+
+from ... import __version__ as core_version
+from ...builders import RevealjsHTMLBuilder
+
+here = Path(__file__).parent
+logger = getLogger(__name__)
+
+
+def register_extra_static_path(app: Sphinx):
+    if not isinstance(app.builder, RevealjsHTMLBuilder):
+        return
+    app.builder.config.revealjs_static_path.append(str(here / "static"))
+    app.builder.add_css_file("sphinx-revealjs/css/footnotes.css")
+
+
+def register_css_context(app: Sphinx, ctx: dict):
+    """Inject config values into builder's globalcontext."""
+    ctx.setdefault(
+        "revealjs_footnotes",
+        {
+            "font_size": app.config.revealjs_footnotes_font_size,
+            "ref_font_size": app.config.revealjs_footnotes_ref_font_size,
+        },
+    )
+
+
+def setup(app: Sphinx):
+    """Entryoint."""
+    app.add_config_value("revealjs_footnotes_font_size", "50%", "env")
+    app.add_config_value("revealjs_footnotes_ref_font_size", "70%", "env")
+    app.connect("builder-inited", register_extra_static_path)
+    app.connect("revealjs:ready-for-writing", register_css_context)
+    return {
+        "version": core_version,
+        "env_version": 1,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

sphinx_revealjs/ext/footnotes/static/sphinx-revealjs/css/footnotes.css_t

@@ -0,0 +1,22 @@
+/**
+ * Customize layout of footnotes.
+ */
+a.footnote-reference {
+  font-size: {{ revealjs_footnotes.ref_font_size }};
+  vertical-align: top;
+}
+
+aside.footnote-list {
+  position: fixed;
+  bottom: 0;
+  font-size: {{ revealjs_footnotes.font_size }};
+  width: 100%;
+}
+
+aside.footnote > span {
+  float: left;
+}
+aside.footnote p {
+  text-align: left;
+  padding-left: 2rem;
+}

tests/roots/test-default/with-footnotes.rst

@@ -0,0 +1,26 @@
+=================
+Test presentation
+=================
+
+Section 1
+=========
+
+Sub 1-1
+-------
+
+First content
+
+Sub 1-2
+-------
+
+Second content [#f1]_
+
+.. [#f1] This is footnote (rendered left-bottom of layout using sphinx.revealjs.footnotes ).
+
+Section 2
+=========
+
+Sub 2-1
+-------
+
+End

tests/test_extensions/test_footnotes.py

@@ -0,0 +1,30 @@
+"""Test cases for sphix_revealjs.ext.footnotes."""
+import pytest
+from sphinx.testing.util import SphinxTestApp
+
+
+@pytest.mark.sphinx(
+    "revealjs",
+    testroot="default",
+    confoverrides={
+        "extensions": ["sphinx_revealjs", "sphinx_revealjs.ext.footnotes"],
+    },
+)
+def test_skip_included(app: SphinxTestApp, status, warning):  # noqa
+    app.build()
+    css_path = app.outdir / "_static/sphinx-revealjs/css/footnotes.css"
+    assert css_path.exists()
+
+
+@pytest.mark.sphinx(
+    "dirrevealjs",
+    testroot="default",
+    freshenv=True,
+    confoverrides={
+        "extensions": ["sphinx_revealjs", "sphinx_revealjs.ext.footnotes"],
+    },
+)
+def test_dirrevealjs(app: SphinxTestApp, status, warning):  # noqa
+    app.build()
+    css_path = app.outdir / "_static/sphinx-revealjs/css/footnotes.css"
+    assert css_path.exists()