Test with multiple versions

.circleci/config.yml

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

pytest.ini

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

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/source/conf.py

@@ -0,0 +1,7 @@
+extensions = [
+    "readthedocs_ext.readthedocs",
+    'sphinx.ext.autosectionlabel',
+]
+project = "Test"
+master_doc = "index"
+exclude_patterns = ["out"]

readthedocs/embed/tests/data/sphinx/source/glossary.rst

@@ -0,0 +1,40 @@
+Glossary
+========
+
+.. glossary::
+
+   builder
+      A class (inheriting from :class:`~sphinx.builders.Builder`) that takes
+      parsed documents and performs an action on them.  Normally, builders
+      translate the documents to an output format, but it is also possible to
+      use builders that e.g. check for broken links in the documentation, or
+      build coverage information.
+
+      See :doc:`/usage` for an overview over Sphinx's built-in
+      builders.
+
+   configuration directory
+      The directory containing :file:`conf.py`.  By default, this is the same as
+      the :term:`builder`, but can be set differently with the **-c**
+      command-line option.
+
+   directive
+      A reStructuredText markup element that allows marking a block of content
+      with special meaning.  Directives are supplied not only by docutils, but
+      Sphinx and custom extensions can add their own.  The basic directive
+      syntax looks like this:
+
+      .. sourcecode:: rst
+
+         .. directivename:: argument ...
+            :option: value
+
+            Content of the directive.
+
+      See :ref:`index:Another title` for more information.
+
+   environment
+      A structure where information about all documents under the root is saved,
+      and used for cross-referencing.  The environment is pickled after the
+      parsing stage, so that successive runs only need to read and parse new and
+      changed documents.

readthedocs/embed/tests/data/sphinx/source/index.rst

@@ -0,0 +1,35 @@
+Title
+=====
+
+`Read the Docs`_ hosts documentation for the open source community.
+
+.. _Read the Docs: https://readthedocs.org
+
+The main documentation for the site is organized into a couple sections:
+
+.. toctree::
+   :maxdepth: 2
+
+   /usage
+   /glossary
+
+Subtitle
+--------
+
+See :term:`builder` for more information.
+
+Sub-sub title
+`````````````
+
+Here is my content.
+
+- One
+- Two
+- Three
+
+Another title
+-------------
+
+.. code-block:: python
+
+   print("Hello world!")

readthedocs/embed/tests/data/sphinx/source/out/glossary-glossary.html

@@ -0,0 +1,34 @@
+  <div class="section" id="glossary">
+<h1>Glossary<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#glossary" title="Permalink to this headline">¶</a></h1>
+<dl class="glossary">
+<dt id="term-builder">builder<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#term-builder" title="Permalink to this term">¶</a></dt><dd><p>A class (inheriting from <code class="xref py py-class docutils literal notranslate"><span class="pre">Builder</span></code>) that takes
+parsed documents and performs an action on them.  Normally, builders
+translate the documents to an output format, but it is also possible to
+use builders that e.g. check for broken links in the documentation, or
+build coverage information.</p>
+<p>See <a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html"><span class="doc">Usage</span></a> for an overview over Sphinx’s built-in
+builders.</p>
+</dd>
+<dt id="term-configuration-directory">configuration directory<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#term-configuration-directory" title="Permalink to this term">¶</a></dt><dd><p>The directory containing <code class="file docutils literal notranslate"><span class="pre">conf.py</span></code>.  By default, this is the same as
+the <a class="reference internal" href="http://project.readthedocs.io/en/latest/index.html#term-builder"><span class="xref std std-term">builder</span></a>, but can be set differently with the <strong>-c</strong>
+command-line option.</p>
+</dd>
+<dt id="term-directive">directive<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#term-directive" title="Permalink to this term">¶</a></dt><dd><p>A reStructuredText markup element that allows marking a block of content
+with special meaning.  Directives are supplied not only by docutils, but
+Sphinx and custom extensions can add their own.  The basic directive
+syntax looks like this:</p>
+<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">directivename</span><span class="p">::</span> argument ...
+   <span class="nc">:option:</span> value
+
+   Content of the directive.
+</pre></div>
+</div>
+<p>See <span class="xref std std-ref">index:Another title</span> for more information.</p>
+</dd>
+<dt id="term-environment">environment<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#term-environment" title="Permalink to this term">¶</a></dt><dd><p>A structure where information about all documents under the root is saved,
+and used for cross-referencing.  The environment is pickled after the
+parsing stage, so that successive runs only need to read and parse new and
+changed documents.</p>
+</dd>
+</dl>
+</div>

readthedocs/embed/tests/data/sphinx/source/out/glossary-term-builder.html

@@ -0,0 +1,8 @@
+<dd><p>A class (inheriting from <code class="xref py py-class docutils literal notranslate"><span class="pre">Builder</span></code>) that takes
+parsed documents and performs an action on them.  Normally, builders
+translate the documents to an output format, but it is also possible to
+use builders that e.g. check for broken links in the documentation, or
+build coverage information.</p>
+<p>See <a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html"><span class="doc">Usage</span></a> for an overview over Sphinx’s built-in
+builders.</p>
+</dd>

readthedocs/embed/tests/data/sphinx/source/out/glossary-term-configuration-directory.html

@@ -0,0 +1,4 @@
+<dd><p>The directory containing <code class="file docutils literal notranslate"><span class="pre">conf.py</span></code>.  By default, this is the same as
+the <a class="reference internal" href="http://project.readthedocs.io/en/latest/index.html#term-builder"><span class="xref std std-term">builder</span></a>, but can be set differently with the <strong>-c</strong>
+command-line option.</p>
+</dd>

readthedocs/embed/tests/data/sphinx/source/out/glossary-term-directive.html

@@ -0,0 +1,12 @@
+<dd><p>A reStructuredText markup element that allows marking a block of content
+with special meaning.  Directives are supplied not only by docutils, but
+Sphinx and custom extensions can add their own.  The basic directive
+syntax looks like this:</p>
+<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">directivename</span><span class="p">::</span> argument ...
+   <span class="nc">:option:</span> value
+
+   Content of the directive.
+</pre></div>
+</div>
+<p>See <span class="xref std std-ref">index:Another title</span> for more information.</p>
+</dd>

readthedocs/embed/tests/data/sphinx/source/out/glossary-term-environment.html

@@ -0,0 +1,5 @@
+<dd><p>A structure where information about all documents under the root is saved,
+and used for cross-referencing.  The environment is pickled after the
+parsing stage, so that successive runs only need to read and parse new and
+changed documents.</p>
+</dd>

readthedocs/embed/tests/data/sphinx/source/out/index-another-title.html

@@ -0,0 +1,6 @@
+<div class="section" id="another-title">
+<h2>Another title<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#another-title" title="Permalink to this headline">¶</a></h2>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Hello world!&quot;</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>

readthedocs/embed/tests/data/sphinx/source/out/index-sub-sub-title.html

@@ -0,0 +1,9 @@
+<div class="section" id="sub-sub-title">
+<h3>Sub-sub title<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#sub-sub-title" title="Permalink to this headline">¶</a></h3>
+<p>Here is my content.</p>
+<ul class="simple">
+<li><p>One</p></li>
+<li><p>Two</p></li>
+<li><p>Three</p></li>
+</ul>
+</div>

readthedocs/embed/tests/data/sphinx/source/out/index-subtitle.html

@@ -0,0 +1,13 @@
+<div class="section" id="subtitle">
+<h2>Subtitle<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#subtitle" title="Permalink to this headline">¶</a></h2>
+<p>See <a class="reference internal" href="http://project.readthedocs.io/en/latest/glossary.html#term-builder"><span class="xref std std-term">builder</span></a> for more information.</p>
+<div class="section" id="sub-sub-title">
+<h3>Sub-sub title<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#sub-sub-title" title="Permalink to this headline">¶</a></h3>
+<p>Here is my content.</p>
+<ul class="simple">
+<li><p>One</p></li>
+<li><p>Two</p></li>
+<li><p>Three</p></li>
+</ul>
+</div>
+</div>

readthedocs/embed/tests/data/sphinx/source/out/index-title.html

@@ -0,0 +1,30 @@
+  <div class="section" id="title">
+<h1>Title<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#title" title="Permalink to this headline">¶</a></h1>
+<p><a class="reference external" href="https://readthedocs.org">Read the Docs</a> hosts documentation for the open source community.</p>
+<p>The main documentation for the site is organized into a couple sections:</p>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="http://project.readthedocs.io/en/latest/usage.html">Usage</a></li>
+<li class="toctree-l1"><a class="reference internal" href="http://project.readthedocs.io/en/latest/glossary.html">Glossary</a></li>
+</ul>
+</div>
+<div class="section" id="subtitle">
+<h2>Subtitle<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#subtitle" title="Permalink to this headline">¶</a></h2>
+<p>See <a class="reference internal" href="http://project.readthedocs.io/en/latest/glossary.html#term-builder"><span class="xref std std-term">builder</span></a> for more information.</p>
+<div class="section" id="sub-sub-title">
+<h3>Sub-sub title<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#sub-sub-title" title="Permalink to this headline">¶</a></h3>
+<p>Here is my content.</p>
+<ul class="simple">
+<li><p>One</p></li>
+<li><p>Two</p></li>
+<li><p>Three</p></li>
+</ul>
+</div>
+</div>
+<div class="section" id="another-title">
+<h2>Another title<a class="headerlink" href="http://project.readthedocs.io/en/latest/index.html#another-title" title="Permalink to this headline">¶</a></h2>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Hello world!&quot;</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+</div>

readthedocs/embed/tests/data/sphinx/source/usage.rst

@@ -0,0 +1,4 @@
+Usage
+=====
+
+Here are some usage examples.