docs: open graph metadata sphinx extension

mdsanima-dev · May 2, 2022 · 74a42bf · 74a42bf
1 parent fe1d693
commit 74a42bf
Show file tree

Hide file tree

Showing 5 changed files with 44 additions and 18 deletions.
diff --git a/docs/_images/mdsanima_dev_python_package.jpg b/docs/_images/mdsanima_dev_python_package.jpg
diff --git a/docs/conf.py b/docs/conf.py
@@ -24,6 +24,7 @@
     "myst_parser",
     "sphinx_copybutton",
     "sphinx_design",
+    "sphinxext.opengraph",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.autosectionlabel",
@@ -86,3 +87,10 @@
     "pull": ("https://github.com/mdsanima-dev/mdsanima-dev/pull/%s", "PR #"),
     "pypi": ("https://pypi.org/project/%s/", ""),
 }
+
+# meta tags config
+ogp_site_url = "https://mdsanima-dev.github.io/mdsanima-dev/"
+ogp_image = ogp_site_url + "_images/mdsanima_dev_python_package.jpg"
+ogp_custom_meta_tags = [
+    '<meta property="twitter:card" content="summary_large_image" />',
+]
diff --git a/docs/project/reference.md b/docs/project/reference.md
@@ -4,17 +4,25 @@ This is a useful links for this documentation site theme and other stuff.
 
 ## REFERENCE `LINKS`
 
-- [Furo Theme Documentation](https://pradyunsg.me/furo/)
-- [Sphinx Python Documentation](https://www.sphinx-doc.org/en/master/)
-- [Sphinx Design Documentation](https://sphinx-design.readthedocs.io)
-- [Sphinx Desing Furo Theme](https://sphinx-design.readthedocs.io/en/furo-theme/)
-- [Sphinx Google Analytics](https://www.sphinx-doc.org/en/master/faq.html)
-- [Packaging Python Projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
-- [PyPA Specificiation](https://packaging.python.org/en/latest/specifications/pypirc/#pypirc)
-- [Publishing Package Using TestPyPI](https://packaging.python.org/en/latest/guides/using-testpypi/)
-- [Publishing Package GitHub Actions](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/)
-- [Shields Metadata Badge](https://shields.io/)
-- [Octicons Icons](https://primer.github.io/octicons/)
-- [Font Awesome Icons](https://fontawesome.com/search?m=free&s=solid)
-- [Google Fonts Icons](https://fonts.google.com/icons?icon.set=Material+Symbols)
-- [Simple Icons](https://simpleicons.org/)
+- [Furo Theme Documentation {octicon}`link-external;0.8em`](https://pradyunsg.me/furo/)
+- [Sphinx Python Documentation {octicon}`link-external;0.8em`](https://www.sphinx-doc.org/en/master/)
+- [Sphinx Design Documentation {octicon}`link-external;0.8em`](https://sphinx-design.readthedocs.io)
+- [Sphinx Desing Furo Theme {octicon}`link-external;0.8em`](https://sphinx-design.readthedocs.io/en/furo-theme/)
+- [Sphinx Google Analytics {octicon}`link-external;0.8em`](https://www.sphinx-doc.org/en/master/faq.html)
+- [Sphinx Open Graph {octicon}`link-external;0.8em`](https://github.com/wpilibsuite/sphinxext-opengraph)
+- [Packaging Python Projects {octicon}`link-external;0.8em`](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
+- [PyPA Specificiation {octicon}`link-external;0.8em`](https://packaging.python.org/en/latest/specifications/pypirc/#pypirc)
+- [Publishing Package Using TestPyPI {octicon}`link-external;0.8em`](https://packaging.python.org/en/latest/guides/using-testpypi/)
+- [Publishing Package GitHub Actions {octicon}`link-external;0.8em`](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/)
+- [Shields Metadata Badge {octicon}`link-external;0.8em`](https://shields.io/)
+- [Octicons Icons {octicon}`link-external;0.8em`](https://primer.github.io/octicons/)
+- [Font Awesome Icons {octicon}`link-external;0.8em`](https://fontawesome.com/search?m=free&s=solid)
+- [Google Fonts Icons {octicon}`link-external;0.8em`](https://fonts.google.com/icons?icon.set=Material+Symbols)
+- [Simple Icons {octicon}`link-external;0.8em`](https://simpleicons.org/)
+
+## DEBUG `META TAG`
+
+- [Facebook Sharing Debugger {octicon}`link-external;0.8em`](https://developers.facebook.com/tools/debug/)
+- [Twitter Card Validator {octicon}`link-external;0.8em`](https://cards-dev.twitter.com/validator)
+- [LinkedIn Post Inspector {octicon}`link-external;0.8em`](https://www.linkedin.com/post-inspector/inspect/)
+- [Meta Tags Tool Generator {octicon}`link-external;0.8em`](https://metatags.io/)
diff --git a/docs/project/theme.md b/docs/project/theme.md
@@ -9,7 +9,8 @@ off.
 
 If you want to check what changes have been made please check the
 `mdsanima.css` file which is in `/docs/_static/` directory on this package
-repository and you can also see it in [changelog](../development/changelog/).
+repository and you can also see it in [changelog](../development/changelog/)
+pages.
 
 You can navigate through the documentation by using the keyboard with the
 Left Arrow {kbd}`<` or Right Arrow {kbd}`>` key.
@@ -35,7 +36,11 @@ icon informing that you are going to another page like
 link which goes to the GitHub **mdsanima-dev** page organization.
 
 In addition, each documented page written in `markdown` should contain an
-appropriate metatag and corrected page title and description.
+appropriate metatag and corrected page title and description. For this options
+we're add [sphinxext-opengraph {octicon}`link-external;0.8em`][opengraph]
+extension to generate OpenGraph metadata. For debug metadata praview how our
+webpage documentation will look on Google, Facebook, Twitter and more please
+check [debug meta tag](../reference/#debug-meta-tag) links section.
 
 ```{important}
 Please just check how this file is written in the repository that generates
@@ -49,6 +54,8 @@ language. My native language is Polish and please don't laugh if something is
 misspelled. Every day I try to improve my writing and speaking in English, but
 this is hard.
 
+[opengraph]: https://github.com/wpilibsuite/sphinxext-opengraph
+
 ## EXAMPLE `MARKDOWN`
 
 Here I show you some examples of how we can write documentation in `markdown`
@@ -138,12 +145,14 @@ icons.
 
 This is a example of adding a `img` or `svg` with custom size.
 
-<img src="../../_static/logo/squere/svg/logo_mdsanima_default_02-sky.svg" width="48" height="48">
+<img src="../../_static/logo/squere/svg/logo_mdsanima_default_02-sky.svg" width="67" height="67">
+<img src="../../_images/mdsanima_dev_python_package.jpg" width="128" height="67">
 
 Markdown should be a this `html` code:
 
 ```markdown
-<img src="../../_static/logo/squere/svg/logo_mdsanima_default_02-sky.svg" width="48" height="48">
+<img src="../../_static/logo/squere/svg/logo_mdsanima_default_02-sky.svg" width="67" height="67">
+<img src="../../_images/mdsanima_dev_python_package.jpg" width="128" height="67">
 ```
 
 ## EXAMPLE `BLOCK CODE`

diff --git a/docs/requirements-dev.txt b/docs/requirements-dev.txt
@@ -2,6 +2,7 @@ Sphinx==4.5.0
 sphinx-copybutton==0.5.0
 sphinx-design==0.0.13
 sphinx-inline-tabs==2022.1.2b11
+sphinxext-opengraph==0.6.3
 myst-parser==0.16.1
 furo==2022.3.4
 wheel==0.37.1