Convert documentation to reStructuredText

Author: AA-Turner

.github/workflows/builddoc.yml

@@ -39,7 +39,7 @@ jobs:
       run: >
         python -m sphinx
         build -M html
-        ./docs/source
+        ./docs
         ./docs/build
         --jobs=auto
         --show-traceback

.readthedocs.yml

@@ -16,4 +16,4 @@ python:
 sphinx:
   builder: html
   fail_on_warning: true
-  configuration: docs/source/conf.py
+  configuration: docs/conf.py

README.rst

@@ -71,7 +71,7 @@ The extension will automatically retrieve your site URL.
   Configuration for automatically creating social media card PNGs for each page.
   For more information, see `the social media cards docs`__.
 
-  __ https://github.com/sphinx-doc/sphinxext-opengraph/blob/main/docs/source/socialcards.md
+  __ https://github.com/sphinx-doc/sphinxext-opengraph/blob/main/docs/socialcards.md
 
 ``ogp_image``
   **Optional.**

docs/source/_static/og-logo.png renamed to docs/_static/og-logo.png

@@ -12,7 +12,7 @@
 
 # -- Path setup --------------------------------------------------------------
 
-sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+sys.path.insert(0, str(Path(__file__).parent.parent))
 
 # -- Project information -----------------------------------------------------
 
@@ -32,7 +32,6 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "myst_parser",
     "sphinx_design",
     "sphinxext.opengraph",
 ]
@@ -68,7 +67,5 @@
 }
 
 # Generate sample social media preview images
-path_script = Path(
-    __file__, "..", "..", "script", "generate_social_card_previews.py"
-).resolve()
-run(("python", path_script), check=False)  # NoQA: S603
+path_script = Path(__file__, "..", "script", "generate_social_card_previews.py").resolve()
+run((sys.executable, path_script), check=False)  # NoQA: S603

docs/source/conf.py renamed to docs/conf.py

@@ -0,0 +1,6 @@
+.. include:: ../README.rst
+
+.. toctree::
+   :hidden:
+
+   socialcards

docs/index.rst

@@ -10,7 +10,6 @@
 
 import random
 from pathlib import Path
-from textwrap import dedent
 
 from sphinxext.opengraph.socialcards import (
     MAX_CHAR_DESCRIPTION,
@@ -22,18 +21,21 @@
 PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
 
 # Dummy lorem text
-lorem = """
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum
-""".split()
+lorem = """Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
+veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum""".split()
 
 kwargs_fig = {
-    "image": PROJECT_ROOT / "docs/source/_static/og-logo.png",
+    "image": PROJECT_ROOT / "docs/_static/og-logo.png",
     "image_mini": PROJECT_ROOT / "sphinxext/opengraph/_static/sphinx-logo-shadow.png",
 }
 
 print("Generating previews of social media cards...")
 plt_objects = create_social_card_objects(**kwargs_fig)
-embed_text = []
+grid_items = []
 for perm in range(20):
     # Create dummy text description and pagetitle for this iteration
     random.shuffle(lorem)
@@ -57,28 +59,16 @@
         plt_objects=plt_objects,
     )
 
-    path_examples_page_folder = PROJECT_ROOT / "docs"
-    embed_text.append(
-        dedent(
-            f"""
-    ````{{grid-item}}
-    ```{{image}} ../{path_out.relative_to(path_examples_page_folder)}
-    ```
-    ````
-    """
-        )
-    )
+    path_examples_page_folder = PROJECT_ROOT / "docs" / "tmp"
+    grid_items.append(f"""\
+   .. grid-item::
 
-embed_text = "\n".join(embed_text)
-embed_text = f"""
-`````{{grid}} 2
-:gutter: 5
+      .. image:: ./tmp/{path_out.name}
+""")
 
-{embed_text}
-`````
-"""
+embed_text = '.. grid:: 2\n   :gutter: 5\n\n' + '\n'.join(grid_items)
 
-# Write markdown text that we can use to embed these images in the docs
+# Write text that we can use to embed these images in the docs
 (PROJECT_ROOT / "docs/tmp/embed.txt").write_text(embed_text)
 
 print("Done generating previews of social media cards...")

docs/script/generate_social_card_previews.py

@@ -0,0 +1,82 @@
+Social media card images
+========================
+
+This extension will automatically generate a PNG meant for sharing documentation links on social media platforms.
+These cards display metadata about the page that you link to, and are meant to catch the attention of readers.
+
+See `the opengraph.xyz website`__ for a way to preview what your social media cards look like.
+Here's an example of what the card for this page looks like:
+
+.. image:: ./tmp/num_0.png
+   :width: 500
+
+__ https://www.opengraph.xyz/
+
+Disable card images
+-------------------
+
+To disable social media card images, use the following configuration:
+
+.. code-block:: python
+   :caption: conf.py
+
+   ogp_social_cards = {
+       "enable": False
+   }
+
+Update the top-right image
+--------------------------
+
+By default the top-right image will use the image specified by ``html_logo`` if it exists.
+To update it, specify another path in the **image** key like so:
+
+.. code-block:: python
+   :caption: conf.py
+
+   ogp_social_cards = {
+       "image": "path/to/image.png",
+   }
+
+.. warning::
+
+   The image cannot be an SVG
+
+   Matplotlib does not support easy plotting of SVG images,
+   so ensure that your image is a PNG or JPEG file, not SVG.
+
+Customize the text font
+-----------------------
+
+By default, the Roboto Flex font is used to render the card text.
+
+You can specify the other font name via ``font`` key:
+
+.. code-block:: python
+   :caption: conf.py
+
+   ogp_social_cards = {
+       "font": "Noto Sans CJK JP",
+   }
+
+You might need to install an additional font package on your environment. Also, note that the font name needs to be
+discoverable by Matplotlib FontManager.
+See `Matplotlib documentation`__
+for the information about FontManager.
+
+__ https://matplotlib.org/stable/tutorials/text/text_props.html#default-font
+
+Customize the card
+------------------
+
+There are several customization options to change the text and look of the social media preview card.
+Below is a summary of these options.
+
+- **site_url**: Set a custom site URL.
+- **line_color**: Colour of the border line at the bottom of the card, in hex format.
+
+Example social cards
+--------------------
+
+Below are several social cards to give an idea for how this extension behaves with different length and size of text.
+
+.. include:: ./tmp/embed.txt

docs/socialcards.rst

@@ -23,7 +23,7 @@ def docs(session: nox.Session) -> None:
     """Build the documentation. Use `-- live` to build with a live server."""
     session.install("--group", "docs")
     session.install("-e", ".")
-    common_args = '-M', 'html', 'docs/source', 'docs/build'
+    common_args = '-M', 'html', 'docs', 'docs/build'
     if "live" in session.posargs:
         session.install("ipython")
         session.install("sphinx-autobuild")

docs/source/index.md

@@ -54,7 +54,6 @@ email = "[email protected]"
 docs = [
     "furo>=2024",
     "matplotlib",
-    "myst-parser>=4",
     "sphinx-design",
     "sphinx~=8.1.0",
 ]