Embed: add tests for glossary and citations and foot notes

.circleci/config.yml

@@ -17,6 +17,14 @@ jobs:
       - run: pip install --user tox
       - run: tox -e py36,codecov
 
+  sphinx-tests:
+    docker:
+      - image: 'cimg/python:3.6'
+    steps:
+      - checkout
+      - run: pip install --user tox
+      - run: tox -c sphinx-tox.ini
+
   checks:
     docker:
       - image: 'cimg/python:3.6'
@@ -45,3 +53,4 @@ workflows:
     jobs:
       - checks
       - tests
+      - sphinx-tests

pytest.ini

@@ -1,8 +1,8 @@
 [pytest]
 addopts = --reuse-db --strict-markers
 markers =
+    sphinxtest
     search
-    serve
     proxito
 python_files = tests.py test_*.py *_tests.py
 filterwarnings =

readthedocs/api/v2/proxied_urls.py

@@ -15,7 +15,7 @@
 api_footer_urls = [
     url(r'footer_html/', ProxiedFooterHTML.as_view(), name='footer_html'),
     url(r'search/$', ProxiedPageSearchAPIView.as_view(), name='search_api'),
-    url(r'embed/', ProxiedEmbedAPI.as_view(), name='embed_api'),
+    url(r'embed/', ProxiedEmbedAPI.as_view(), name='api_embed'),
     url(r'analytics/$', AnalyticsView.as_view(), name='analytics_api'),
 ]
 

readthedocs/conftest.py

@@ -1,6 +1,8 @@
 import pytest
 from rest_framework.test import APIClient
 
+pytest_plugins = 'sphinx.testing.fixtures'
+
 @pytest.fixture
 def api_client():
     return APIClient()

readthedocs/embed/tests/data/sphinx/bibtex/page-getting-started.html

@@ -0,0 +1,166 @@
+<div class="section" id="getting-started">
+  <h1>Getting Started<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#getting-started" title="Permalink to this headline">¶</a></h1>
+  <div class="section" id="overview">
+    <h2>Overview<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#overview" title="Permalink to this headline">¶</a></h2>
+    <p>Sphinx extension for BibTeX style citations.</p>
+    <p>
+      The bibtex extension allows <a class="reference external" href="http://www.bibtex.org/">BibTeX</a>
+      citations to be inserted into documentation generated by
+      <a class="reference external" href="https://www.sphinx-doc.org/en/master/">Sphinx</a>, via
+      a <code class="docutils literal notranslate"><span class="pre">bibliography</span></code> directive,
+      along with <code class="docutils literal notranslate"><span class="pre">:cite:p:</span></code> and <code
+        class="docutils literal notranslate"><span class="pre">:cite:t:</span></code> roles.
+      These work similarly to LaTeX\u2019s <code
+        class="docutils literal notranslate"><span class="pre">thebibliography</span></code> environment
+      and the <code class="docutils literal notranslate"><span class="pre">\\citet</span></code> and <code
+        class="docutils literal notranslate"><span class="pre">\\citep</span></code> commands.
+    </p>
+    <p>
+      For formatting, the extension relies on <a class="reference external" href="https://pybtex.org/">pybtex</a>
+      written by Andrey Golovizin. The extension is inspired by Matthew Brett’s
+      <a class="reference external" href="https://github.com/matthew-brett/bibstuff">bibstuff.sphinxext.bibref</a>
+      and Weston Nielson’s
+      <a class="reference external"
+        href="https://github.com/mcmtroffaes/sphinxcontrib-bibtex/blob/develop/test/natbib.py">sphinx-natbib</a>.
+    </p>
+    <ul class="simple">
+      <li>
+        <p>
+          Download: <a class="reference external"
+            href="https://pypi.org/project/sphinxcontrib-bibtex/#files">https://pypi.org/project/sphinxcontrib-bibtex/#files</a>
+        </p>
+      </li>
+      <li>
+        <p>
+          Documentation: <a class="reference external"
+            href="https://sphinxcontrib-bibtex.readthedocs.io/en/latest/">https://sphinxcontrib-bibtex.readthedocs.io/en/latest/</a>
+        </p>
+      </li>
+      <li>
+        <p>
+          Development: <a class="reference external"
+            href="https://github.com/mcmtroffaes/sphinxcontrib-bibtex/">https://github.com/mcmtroffaes/sphinxcontrib-bibtex/</a>
+        </p>
+      </li>
+    </ul>
+  </div>
+  <div class="section" id="installation">
+    <h2>Installation<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#installation" title="Permalink to this headline">¶</a></h2>
+    <p>
+      Install the module with <code
+        class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">sphinxcontrib-bibtex</span></code>,
+      or from source using <code
+        class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></code>.
+      Then add:
+    </p>
+    <div class="highlight-python notranslate">
+      <div class="highlight">
+        <pre><span></span><span class="n">extensions</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;sphinxcontrib.bibtex&#39;</span><span class="p">]</span>
+<span class="n">bibtex_bibfiles</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;refs.bib&#39;</span><span class="p">]</span>
+</pre>
+      </div>
+    </div>
+    <p>
+      to your project’s Sphinx configuration file <code
+        class="docutils literal notranslate"><span class="pre">conf.py</span></code>.
+    </p>
+  </div>
+  <div class="section" id="minimal-example">
+    <h2>Minimal Example<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#minimal-example" title="Permalink to this headline">¶</a></h2>
+    <p>
+      In your project\u2019s documentation, you can use
+      <code class="docutils literal notranslate"><span class="pre">:cite:t:</span></code> for textual citation
+      references,
+      <code class="docutils literal notranslate"><span class="pre">:cite:p:</span></code> for parenthetical citation
+      references, and <code
+        class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">bibliography::</span></code>
+      for inserting the bibliography. For <a class="reference external"
+        href="https://github.com/mcmtroffaes/sphinxcontrib-bibtex/tree/develop/test/roots/test-debug_minimal_example">example</a>:
+    </p>
+    <div class="highlight-rest notranslate">
+      <div class="highlight">
+        <pre><span></span>See <span class="na">:cite:t:</span><span class="nv">`1987:nelson`</span> for an introduction to non-standard analysis.
+Non-standard analysis is fun <span class="na">:cite:p:</span><span class="nv">`1987:nelson`</span>.
+
+<span class="p">..</span> <span class="ow">bibliography</span><span class="p">::</span>
+</pre>
+      </div>
+    </div>
+    <p>
+      where <code class="file docutils literal notranslate"><span class="pre">refs.bib</span></code> would contain an
+      entry:
+    </p>
+    <div class="highlight-default notranslate">
+      <div class="highlight">
+        <pre><span></span><span class="nd">@Book</span><span class="p">{</span><span class="mi">1987</span><span class="p">:</span><span class="n">nelson</span><span class="p">,</span>
+  <span class="n">author</span> <span class="o">=</span> <span class="p">{</span><span class="n">Edward</span> <span class="n">Nelson</span><span class="p">},</span>
+  <span class="n">title</span> <span class="o">=</span> <span class="p">{</span><span class="n">Radically</span> <span class="n">Elementary</span> <span class="n">Probability</span> <span class="n">Theory</span><span class="p">},</span>
+  <span class="n">publisher</span> <span class="o">=</span> <span class="p">{</span><span class="n">Princeton</span> <span class="n">University</span> <span class="n">Press</span><span class="p">},</span>
+  <span class="n">year</span> <span class="o">=</span> <span class="p">{</span><span class="mi">1987</span><span class="p">}</span>
+<span class="p">}</span>
+</pre>
+      </div>
+    </div>
+    <p>In the default style, this will get rendered as:</p>
+    <p>
+      See Nelson <a class="reference internal" href="http://project.readthedocs.io/en/latest/index.html#nel87a" id="id1"><span>[Nel87a]</span></a> for an introduction to
+      non-standard analysis.
+      Non-standard analysis is fun <a class="reference internal" href="http://project.readthedocs.io/en/latest/index.html#nel87a" id="id2"><span>[Nel87a]</span></a>.</p>
+    <dl class="citation">
+      <dt class="label" id="nel87a"><span class="brackets">Nel87a</span><span class="fn-backref">(<a
+            href="http://project.readthedocs.io/en/latest/index.html#id1">1</a>,<a href="http://project.readthedocs.io/en/latest/index.html#id2">2</a>)</span></dt>
+      <dd>
+        <p>Edward Nelson. <em>Radically Elementary Probability Theory</em>. Princeton University Press, 1987.</p>
+      </dd>
+    </dl>
+    <p>
+      Citations in sphinx are resolved globally across all documents.
+      Typically, you have a single <a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html#directive-bibliography"
+        title="bibliography directive"><code
+          class="xref rst rst-dir docutils literal notranslate"><span class="pre">bibliography</span></code></a>
+      directive across
+      your entire project which collects all citations.
+      Advanced use cases with multiple <a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html#directive-bibliography"
+        title="bibliography directive"><code
+          class="xref rst rst-dir docutils literal notranslate"><span class="pre">bibliography</span></code></a>
+      directives
+      across your project are also supported, but some care
+      needs to be taken from your end to avoid duplicate citations.
+    </p>
+    <p>
+      In contrast, footnotes in sphinx are resolved locally per document.
+      To achieve local bibliographies per document, you can use citations
+      represented by footnotes as follows:
+    </p>
+    <div class="highlight-rest notranslate">
+      <div class="highlight">
+        <pre><span></span>Non-standard analysis is lovely. <span class="na">:footcite:</span><span class="nv">`1987:nelson`</span>
+
+<span class="p">..</span> <span class="ow">footbibliography</span><span class="p">::</span>
+</pre>
+      </div>
+    </div>
+    <p>which will get rendered as:</p>
+    <p>Non-standard analysis is lovely. <a class="footnote-reference brackets" href="http://project.readthedocs.io/en/latest/index.html#nel87b" id="id3">1</a></p>
+    <dl class="footnote brackets">
+      <dt class="label" id="nel87b"><span class="brackets"><a class="fn-backref" href="http://project.readthedocs.io/en/latest/index.html#id3">1</a></span></dt>
+      <dd>
+        <p>Edward Nelson. <em>Radically Elementary Probability Theory</em>. Princeton University Press, 1987.</p>
+      </dd>
+    </dl>
+    <p>
+      Typically, you have a single <a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html#directive-footbibliography"
+        title="footbibliography directive"><code
+          class="xref rst rst-dir docutils literal notranslate"><span class="pre">footbibliography</span></code></a>
+      directive
+      at the bottom of each document that has <a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html#role-footcite"
+        title="footcite role"><code
+          class="xref rst rst-role docutils literal notranslate"><span class="pre">footcite</span></code></a> citations.
+      Advanced use cases with multiple <a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html#directive-footbibliography"
+        title="footbibliography directive"><code
+          class="xref rst rst-dir docutils literal notranslate"><span class="pre">footbibliography</span></code></a>
+      directives per document are also supported. Since everything is local,
+      there is no concern with duplicate citations when using footnotes.
+    </p>
+  </div>
+</div>

readthedocs/embed/tests/data/sphinx/bibtex/page-installation.html

@@ -0,0 +1,21 @@
+  <div class="section" id="installation">
+    <h2>Installation<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#installation" title="Permalink to this headline">¶</a></h2>
+    <p>
+      Install the module with <code
+        class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">sphinxcontrib-bibtex</span></code>,
+      or from source using <code
+        class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></code>.
+      Then add:
+    </p>
+    <div class="highlight-python notranslate">
+      <div class="highlight">
+        <pre><span></span><span class="n">extensions</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;sphinxcontrib.bibtex&#39;</span><span class="p">]</span>
+<span class="n">bibtex_bibfiles</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;refs.bib&#39;</span><span class="p">]</span>
+</pre>
+      </div>
+    </div>
+    <p>
+      to your project’s Sphinx configuration file <code
+        class="docutils literal notranslate"><span class="pre">conf.py</span></code>.
+    </p>
+  </div>

readthedocs/embed/tests/data/sphinx/bibtex/page-minimal-example.html

@@ -0,0 +1,98 @@
+  <div class="section" id="minimal-example">
+    <h2>Minimal Example<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#minimal-example" title="Permalink to this headline">¶</a></h2>
+    <p>
+      In your project\u2019s documentation, you can use
+      <code class="docutils literal notranslate"><span class="pre">:cite:t:</span></code> for textual citation
+      references,
+      <code class="docutils literal notranslate"><span class="pre">:cite:p:</span></code> for parenthetical citation
+      references, and <code
+        class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">bibliography::</span></code>
+      for inserting the bibliography. For <a class="reference external"
+        href="https://github.com/mcmtroffaes/sphinxcontrib-bibtex/tree/develop/test/roots/test-debug_minimal_example">example</a>:
+    </p>
+    <div class="highlight-rest notranslate">
+      <div class="highlight">
+        <pre><span></span>See <span class="na">:cite:t:</span><span class="nv">`1987:nelson`</span> for an introduction to non-standard analysis.
+Non-standard analysis is fun <span class="na">:cite:p:</span><span class="nv">`1987:nelson`</span>.
+
+<span class="p">..</span> <span class="ow">bibliography</span><span class="p">::</span>
+</pre>
+      </div>
+    </div>
+    <p>
+      where <code class="file docutils literal notranslate"><span class="pre">refs.bib</span></code> would contain an
+      entry:
+    </p>
+    <div class="highlight-default notranslate">
+      <div class="highlight">
+        <pre><span></span><span class="nd">@Book</span><span class="p">{</span><span class="mi">1987</span><span class="p">:</span><span class="n">nelson</span><span class="p">,</span>
+  <span class="n">author</span> <span class="o">=</span> <span class="p">{</span><span class="n">Edward</span> <span class="n">Nelson</span><span class="p">},</span>
+  <span class="n">title</span> <span class="o">=</span> <span class="p">{</span><span class="n">Radically</span> <span class="n">Elementary</span> <span class="n">Probability</span> <span class="n">Theory</span><span class="p">},</span>
+  <span class="n">publisher</span> <span class="o">=</span> <span class="p">{</span><span class="n">Princeton</span> <span class="n">University</span> <span class="n">Press</span><span class="p">},</span>
+  <span class="n">year</span> <span class="o">=</span> <span class="p">{</span><span class="mi">1987</span><span class="p">}</span>
+<span class="p">}</span>
+</pre>
+      </div>
+    </div>
+    <p>In the default style, this will get rendered as:</p>
+    <p>
+      See Nelson <a class="reference internal" href="http://project.readthedocs.io/en/latest/index.html#nel87a" id="id1"><span>[Nel87a]</span></a> for an introduction to
+      non-standard analysis.
+      Non-standard analysis is fun <a class="reference internal" href="http://project.readthedocs.io/en/latest/index.html#nel87a" id="id2"><span>[Nel87a]</span></a>.</p>
+    <dl class="citation">
+      <dt class="label" id="nel87a"><span class="brackets">Nel87a</span><span class="fn-backref">(<a
+            href="http://project.readthedocs.io/en/latest/index.html#id1">1</a>,<a href="http://project.readthedocs.io/en/latest/index.html#id2">2</a>)</span></dt>
+      <dd>
+        <p>Edward Nelson. <em>Radically Elementary Probability Theory</em>. Princeton University Press, 1987.</p>
+      </dd>
+    </dl>
+    <p>
+      Citations in sphinx are resolved globally across all documents.
+      Typically, you have a single <a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html#directive-bibliography"
+        title="bibliography directive"><code
+          class="xref rst rst-dir docutils literal notranslate"><span class="pre">bibliography</span></code></a>
+      directive across
+      your entire project which collects all citations.
+      Advanced use cases with multiple <a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html#directive-bibliography"
+        title="bibliography directive"><code
+          class="xref rst rst-dir docutils literal notranslate"><span class="pre">bibliography</span></code></a>
+      directives
+      across your project are also supported, but some care
+      needs to be taken from your end to avoid duplicate citations.
+    </p>
+    <p>
+      In contrast, footnotes in sphinx are resolved locally per document.
+      To achieve local bibliographies per document, you can use citations
+      represented by footnotes as follows:
+    </p>
+    <div class="highlight-rest notranslate">
+      <div class="highlight">
+        <pre><span></span>Non-standard analysis is lovely. <span class="na">:footcite:</span><span class="nv">`1987:nelson`</span>
+
+<span class="p">..</span> <span class="ow">footbibliography</span><span class="p">::</span>
+</pre>
+      </div>
+    </div>
+    <p>which will get rendered as:</p>
+    <p>Non-standard analysis is lovely. <a class="footnote-reference brackets" href="http://project.readthedocs.io/en/latest/index.html#nel87b" id="id3">1</a></p>
+    <dl class="footnote brackets">
+      <dt class="label" id="nel87b"><span class="brackets"><a class="fn-backref" href="http://project.readthedocs.io/en/latest/index.html#id3">1</a></span></dt>
+      <dd>
+        <p>Edward Nelson. <em>Radically Elementary Probability Theory</em>. Princeton University Press, 1987.</p>
+      </dd>
+    </dl>
+    <p>
+      Typically, you have a single <a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html#directive-footbibliography"
+        title="footbibliography directive"><code
+          class="xref rst rst-dir docutils literal notranslate"><span class="pre">footbibliography</span></code></a>
+      directive
+      at the bottom of each document that has <a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html#role-footcite"
+        title="footcite role"><code
+          class="xref rst rst-role docutils literal notranslate"><span class="pre">footcite</span></code></a> citations.
+      Advanced use cases with multiple <a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html#directive-footbibliography"
+        title="footbibliography directive"><code
+          class="xref rst rst-dir docutils literal notranslate"><span class="pre">footbibliography</span></code></a>
+      directives per document are also supported. Since everything is local,
+      there is no concern with duplicate citations when using footnotes.
+    </p>
+  </div>

readthedocs/embed/tests/data/sphinx/bibtex/page-nel87a.html

@@ -0,0 +1,3 @@
+      <dd>
+        <p>Edward Nelson. <em>Radically Elementary Probability Theory</em>. Princeton University Press, 1987.</p>
+      </dd>

readthedocs/embed/tests/data/sphinx/bibtex/page-nel87b.html

@@ -0,0 +1,6 @@
+    <dl class="footnote brackets">
+      <dt class="label" id="nel87b"><span class="brackets"><a class="fn-backref" href="http://project.readthedocs.io/en/latest/index.html#id3">1</a></span></dt>
+      <dd>
+        <p>Edward Nelson. <em>Radically Elementary Probability Theory</em>. Princeton University Press, 1987.</p>
+      </dd>
+    </dl>