Configure Sphinx for Markdown support (#6711)

docs/conf.py

@@ -19,6 +19,8 @@ from datetime import datetime
 
 import django
 
+from recommonmark.transform import AutoStructify
+
 from wagtail import VERSION, __version__
 
 
@@ -54,6 +56,7 @@ os.environ['DATABASE_ENGINE'] = 'django.db.backends.sqlite3'
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
+    'recommonmark',
 ]
 
 if not on_rtd:
@@ -300,3 +303,10 @@ texinfo_documents = [
 def setup(app):
     app.add_css_file('css/custom.css')
     app.add_js_file('js/banner.js')
+
+    github_doc_root = 'https://github.com/wagtail/wagtail/tree/master/docs/'
+
+    app.add_config_value('recommonmark_config', {
+        'url_resolver': lambda url: github_doc_root + url,
+    }, True)
+    app.add_transform(AutoStructify)

docs/reference/contrib/legacy_richtext.md

@@ -0,0 +1,24 @@
+# Legacy richtext
+
+```eval_rst
+.. module:: wagtail.contrib.legacy.richtext
+```
+
+Provides the legacy richtext wrapper.
+
+Place `wagtail.contrib.legacy.richtext` before `wagtail.core` in  `INSTALLED_APPS`.
+
+```python
+INSTALLED_APPS = [
+    ...
+    "wagtail.contrib.legacy.richtext",
+    "wagtail.core",
+    ...
+]
+```
+
+The `{{ page.body|richtext }}` template filter will now render:
+
+```html+django
+<div class="rich-text">...</div>
+```

docs/reference/contrib/legacy_richtext.rst

@@ -1,26 +0,0 @@
-.. _legacy_richtext:
-
-=====================
-Legacy richtext
-=====================
-
-.. module:: wagtail.contrib.legacy.richtext
-
-Provides the legacy richtext wrapper.
-
-Place ``wagtail.contrib.legacy.richtext`` before ``wagtail.core`` in  ``INSTALLED_APPS``.
-
- .. code-block:: python
-
-    INSTALLED_APPS = [
-        ...
-        "wagtail.contrib.legacy.richtext",
-        "wagtail.core",
-        ...
-    ]
-
-The ``{{ page.body|richtext }}`` template filter will now render:
-
- .. code-block:: html+django
-
-    <div class="rich-text">...</div>

docs/releases/2.10.rst

@@ -81,7 +81,7 @@ Other features
  * Add ``after_edit_snippet``, ``after_create_snippet`` and ``after_delete_snippet`` hooks and documentation (Kalob Taulien)
  * Improve performance of empty search results by avoiding downloading the entire search index in these scenarios (Lars van de Kerkhof, Coen van der Kamp)
  * Replace ``gulp-sass`` with ``gulp-dart-sass`` to improve core development across different platforms (Thibaud Colas)
- * Remove markup around rich text rendering by default, provide a way to use old behaviour via ``wagtail.contrib.legacy.richtext``. See :ref:`legacy_richtext`. (Coen van der Kamp, Dan Braghis)
+ * Remove markup around rich text rendering by default, provide a way to use old behaviour via ``wagtail.contrib.legacy.richtext``. See :doc:`/reference/contrib/legacy_richtext`. (Coen van der Kamp, Dan Braghis)
  * Add ``WAGTAIL_TIME_FORMAT`` setting (Jacob Topp-Mugglestone)
  * Apply title length normalisation to improve ranking on PostgreSQL search (Karl Hobley)
  * Allow omitting the default editor from ``WAGTAILADMIN_RICH_TEXT_EDITORS`` (Gassan Gousseinov)
@@ -160,7 +160,7 @@ Key points:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In previous releases, rich text values were enclosed in a ``<div class="rich-text">`` element when rendered; this element has now been removed.
-To restore the old behaviour, see :ref:`legacy_richtext`.
+To restore the old behaviour, see :doc:`/reference/contrib/legacy_richtext`.
 
 
 Prepopulating data for site history report

setup.py

@@ -76,6 +76,7 @@ documentation_extras = [
     'Sphinx>=1.5.2',
     'sphinx-autobuild>=0.6.0',
     'sphinx_rtd_theme>=0.1.9',
+    'recommonmark>=0.7.1',
 ]
 
 setup(