Merge pull request #209 from QGIS-Contribution/doc/spring-upgrade

Upgrade to latest furo and myst parser options

docs/conf.py

@@ -1,4 +1,12 @@
+#!python3
+
+"""
+    Configuration for project documentation using Sphinx.
+"""
+
+# standard
 from os import environ, path
+from datetime import datetime
 import sys
 
 sys.path.insert(0, path.abspath(".."))
@@ -13,15 +21,11 @@
 project = __about__.__title__
 author = __about__.__author__
 copyright = __about__.__copyright__
+description = __about__.__summary__
 version = release = __about__.__version__
 github_doc_root = "{}/tree/master/doc/".format(__about__.__uri_repository__)
 
 
-# replacement variables
-rst_epilog = ".. |title| replace:: %s" % project
-rst_epilog += "\n.. |author| replace:: %s" % author
-rst_epilog += "\n.. |repo_url| replace:: %s" % __about__.__uri_repository__
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -30,23 +34,21 @@
 extensions = [
     # Sphinx included
     "sphinx.ext.autosectionlabel",
+    "sphinx.ext.extlinks",
     "sphinx.ext.githubpages",
     "sphinx.ext.intersphinx",
-    "sphinx.ext.extlinks",
     "sphinx.ext.viewcode",
     # 3rd party
-    "sphinx_copybutton",
     "myst_parser",
+    "sphinx_copybutton",
+    "sphinxext.opengraph",
 ]
 
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
+source_suffix = {".md": "markdown", ".rst": "restructuredtext"}
 autosectionlabel_prefix_document = True
 # The master toctree document.
 master_doc = "index"
@@ -56,7 +58,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+# language = None
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -79,4 +81,49 @@
 # -- EXTENSIONS --------------------------------------------------------
 
 # Configuration for intersphinx (refer to others docs).
-intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
+intersphinx_mapping = {
+    "PyQt5": ("https://www.riverbankcomputing.com/static/Docs/PyQt5", None),
+    "python": ("https://docs.python.org/3/", None),
+    "qgis": ("https://qgis.org/pyqgis/master/", None),
+}
+
+# MyST Parser
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    "substitution",
+]
+
+myst_substitutions = {
+    "author": author,
+    "date_update": datetime.now().strftime("%d %B %Y"),
+    "description": description,
+    "qgis_version_max": __about__.__plugin_md__.get("general").get(
+        "qgismaximumversion"
+    ),
+    "qgis_version_min": __about__.__plugin_md__.get("general").get(
+        "qgisminimumversion"
+    ),
+    "repo_url": __about__.__uri__,
+    "title": project,
+    "version": version,
+}
+
+myst_url_schemes = ("http", "https", "mailto")
+
+# OpenGraph
+ogp_image = "https://qgis-contribution.github.io/QGIS-ResourceSharing/_images/collection_preview.png"
+ogp_site_name = project
+ogp_site_url = __about__.__uri_homepage__
+ogp_custom_meta_tags = [
+    "<meta name='twitter:card' content='summary_large_image'>",
+    f'<meta property="twitter:description" content="{description}" />',
+    f'<meta property="twitter:image" content="{ogp_image}" />',
+    f'<meta property="twitter:title" content="{project}" />',
+]

docs/index.md

@@ -1,5 +1,13 @@
 # QGIS Resource Sharing - Documentation
 
+> **Description :** {{ description }}  
+> **Author and contributors:** {{ author }}  
+> **Plugin version:** {{ version }}  
+> **QGIS minimum version:** {{ qgis_version_min }}  
+> **QGIS maximum version:** {{ qgis_version_max }}  
+> **Source code:** {{ repo_url }}  
+> **Last documentation update:** {{ date_update }}
+
 ## Introduction
 
 ![the plugin](assets/img/app.png)

requirements/documentation.txt

@@ -3,7 +3,7 @@
 
 furo==2021.4.11b34
 ghp-import>2.0,<2.1
-myst-parser>=0.13,<0.15
+myst-parser[linkify]>=0.13,<0.15
 sphinx-autobuild==2021.3.14
 sphinx-copybutton>=0.3,<0.4
 sphinxext-opengraph>=0.4,<0.5