docs: add image to getting started page

build: fix config for documentation

docs/conf.py

@@ -1,25 +1,25 @@
-# Copyritht © 2022 Marcin Różewski MDSANIMA
+# Copyritht © 2021-2023 Marcin Różewski MDSANIMA
 
 
-"""Sphinx configuration file for ``mdsanima-dev`` package documentation."""
+"""Sphinx documentation configuration file for `mdsanima-dev` package."""
 
 
 import os
 import sys
 
 
-# append path
+# Append absolute path.
 sys.path.append(os.path.abspath("."))
 
 
-# project information
+# Project information.
 project = "mdsanima-dev"
 copyright = "2021-2023, Marcin Różewski MDSANIMA"
 author = "Marcin Różewski"
 master_doc = "index"
 language = "en"
 
-# sphinx extension modules
+# Sphinx extension modules.
 extensions = [
     "myst_parser",
     "sphinx_copybutton",
@@ -35,66 +35,60 @@
     "sphinx.ext.mathjax",
 ]
 
-# markdown parser
+# Markdown parser.
 source_suffix = {
     ".md": "markdown",
 }
 
-# font awesome
-fontawesome_css = "https://use.fontawesome.com/releases/v5.6.1/css/all.css"
-cdnfa = "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/"
-fontawesome_min = cdnfa + "fontawesome.min.css"
-solid_min = cdnfa + "solid.min.css"
-brands_min = cdnfa + "brands.min.css"
+# Fontawesome options.
+FONTAWESOME_CSS_A = "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/fontawesome.min.css"
+FONTAWESOME_CSS_B = "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/solid.min.css"
+FONTAWESOME_CSS_C = "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/brands.min.css"
 
-# path options
+# Path options.
 templates_path = ["_templates"]
 exclude_patterns = ["_images"]
 html_static_path = ["_static"]
-html_css_files = ["mdsanima.css", fontawesome_css]
 html_js_files = ["mdsanima.js"]
+html_css_files = ["mdsanima.css", FONTAWESOME_CSS_A, FONTAWESOME_CSS_B, FONTAWESOME_CSS_C]
 
-# theme options
+# Theme options.
 html_theme = "furo"
-html_logo = "_static/logo/filled/svg/logo_mdsanima_default_02-sky.svg"
-html_favicon = "_static/logo/squere/png/logo_mdsanima_default_02-sky_1x.png"
+html_logo = "_static/images/mdsanima_logo_rc2_light_01_cyan.png"
+html_favicon = "_static/images/mdsanima_logo_rc2_light_01_cyan.svg"
 
-# html options
+# HTML options.
 html_show_sphinx = True
 html_last_updated_fmt = "%d %B %Y, at %H:%M:%S"
 
-# theme options custom
+# Theme custom options.
 html_theme_options = {
     "navigation_with_keys": True,
     "sidebar_hide_name": False,
     "footer_icons": [
         {
             "name": "GitHub",
             "url": "https://github.com/mdsanima-dev/mdsanima-dev/",
-            "html": """
-                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
-                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
-                </svg>
-            """,
-            "class": "",
+            "html": "",
+            "class": "fa-brands fa-solid fa-github fa-2x",
         },
     ],
 }
 
-# extlinks options
+# External links options.
 extlinks = {
     "issue": ("https://github.com/mdsanima-dev/mdsanima-dev/issues/%s", "#"),
     "pull": ("https://github.com/mdsanima-dev/mdsanima-dev/pull/%s", "PR #"),
     "pypi": ("https://pypi.org/project/%s/", ""),
 }
 
-# meta tags config
+# Meta tags config.
 ogp_site_url = "https://mdsanima-dev.github.io/mdsanima-dev/"
-ogp_image = ogp_site_url + "_static/images/mdsanima_dev_python_package.jpg"
+ogp_image = ogp_site_url + "_static/images/mdsanima_dev_python_package.webp"
 ogp_custom_meta_tags = [
     '<meta property="twitter:card" content="summary_large_image" />',
 ]
 
-# myst parser config
+# Myst parser config.
 myst_all_links_external = True
 myst_heading_anchors = 4

docs/getting-started.md

@@ -3,6 +3,8 @@
 Instructions how to install the _Python_ package [mdsanima-dev {octicon}`link-external;0.8em`][pypi-mdsanima-dev] on
 your system.
 
+<img src="../../_static/images/mdsanima_dev_python_package.webp">
+
 ## INSTALLATION `OPTIONS`
 
 ```{include} ../README.md

docs/project/theme.md

@@ -1,65 +1,52 @@
 # {octicon}`gear;1em;sd-text-secondary` `THEME`
 
-This documentation site is generated with the Sphinx and the customized Furo
-theme.
+This documentation site is generated with the Sphinx and the customized Furo theme.
 
-I make this theme is a complete different that's original Furo theme. It is
-customized to my needs and, above all, the light theme options have been turned
-off.
+I make this theme is a complete different that's original Furo theme. It is customized to my needs and, above all, the
+light theme options have been turned 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/)
-pages.
+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/) pages.
 
-You can navigate through the documentation by using the keyboard with the
-Left Arrow {kbd}`<` or Right Arrow {kbd}`>` key.
+You can navigate through the docs by using the keyboard with the Left Arrow {kbd}`<` or Right Arrow {kbd}`>` key.
 
 ## THEME `CUSTOMIZED`
 
-All `markdown` files that we write in this repository for documentation or
-quick tutorials that will also been posted in this repository must be written
-in a specific way to maintain unity and transparency.
+All `markdown` files that we write in this repository for documentation or quick tutorials that will also been posted in
+this repository must be written in a specific way to maintain unity and transparency.
 
 ```{attention}
-The `markdown` file must be started just like any other file that is now in the
-documentation. The first paragraph must contain an `octicon` and a name in the
-backtick that generates a capital literal code. The second paragraph and the
-others must also be capitalized, the first part must be normally spelled and
-the second part of the name in the backtick code letter.
+The `markdown` file must be started just like any other file that is now in the documentation. The first paragraph must
+contain an `octicon` and a name in the backtick that generates a capital literal code. The second paragraph and the
+others must also be capitalized, the first part must be normally spelled and the second part of the name in the backtick
+code letter.
 ```
 
-All internal links should be look like [this example](#theme-customized) link.
-However, all external links that lead to other pages should also contain an
-icon informing that you are going to another page like
-[this example {octicon}`link-external;0.8em`](https://github.com/mdsanima-dev/)
-link which goes to the GitHub **mdsanima-dev** page organization.
+All internal links should be look like [this example](#theme-customized) link. However, all external links that lead to
+other pages should also contain an icon informing that you are going to another page like
+[this example {octicon}`link-external;0.8em`](https://github.com/mdsanima-dev/) 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. 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.
+In addition, each documented page written in `markdown` should contain an 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
-this page. We also adhere to the fact that files written in markdown for
-documentation should be written up to 79 characters per line. There may be
-exceptions when adding a link and there may be more characters on one line.
+Please just check how this file is written in the repository that generates this page. We also adhere to the fact that
+files written in markdown for documentation should be written up to 79 characters per line. There may be exceptions when
+adding a link and there may be more characters on one line.
 ```
 
-It may also happen that the text is not written correctly in the English
-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.
+It may also happen that the text is not written correctly in the English 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 for me.
 
 [opengraph]: https://github.com/wpilibsuite/sphinxext-opengraph
 
 ## EXAMPLE `MARKDOWN`
 
-Here I show you some examples of how we can write documentation in `markdown`
-file with reStructuredText `rst` directive.
+Here is some examples of how we can write documentation in `markdown` file with reStructuredText `rst` directive.
 
 This is a `code-literal` text written in `markdown` file.
 
@@ -81,8 +68,7 @@ You can also make this {code}`example code` literal with `rst` directives code:
 
 ## EXAMPLE `ICONS`
 
-This is an example of **Font Awesome Icons** with custom size and color with
-standard `html` code.
+This is an example of **Font Awesome Icons** with custom size and color with standard `html` code.
 
 <i class='fab fa-markdown' style='font-size:24px;color:red'></i>
 <i class="fas fa-terminal"></i>
@@ -98,14 +84,14 @@ Markdown should be a this `html` code:
 
 You can also make this icons with `rst` directive.
 
-{fas}`fa-solid fa-markdown fa-2x sd-text-primary`
+{fab}`fa-solid fa-markdown fa-2x sd-text-primary`
 {fas}`fa-solid fa-terminal fa-2x sd-text-info`
 {fab}`fa-solid fa-bitcoin fa-2x sd-text-warning`
 
 Markdown should be a this `rst` directive code:
 
 ```markdown
-{fas}`fa-solid fa-markdown fa-2x sd-text-primary`
+{fab}`fa-solid fa-markdown fa-2x sd-text-primary`
 {fas}`fa-solid fa-terminal fa-2x sd-text-info`
 {fab}`fa-solid fa-bitcoin fa-2x sd-text-warning`
 ```
@@ -138,45 +124,41 @@ Markdown should be a this `rst` directive code:
 {octicon}`report;48px;sd-text-muted`
 ```
 
-When you want to add the same icon, but in directives `eval-rst` inside
-`markdown` file you must use a colon instead of the curly brace `{fas}` and
-`{octicon}` like this `:fas:` and `:octicon:` and rest of code to generate
-icons.
+When you want to add the same icon, but in directives `eval-rst` inside `markdown` file you must use a colon instead of
+the curly brace `{fas}` and `{octicon}` like this `:fas:` and `:octicon:` and rest of code to generate 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="67" height="67">
 <img src="../../_static/images/mdsanima_dev_python_package.jpg" width="128" height="67">
+<img src="../../_static/images/mdsanima_logo_rc2_light_01_cyan.svg" width="90" height="67">
+<img src="../../_static/images/mdsanima_dev_python_package.webp" 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="67" height="67">
 <img src="../../_static/images/mdsanima_dev_python_package.jpg" width="128" height="67">
+<img src="../../_static/images/mdsanima_logo_rc2_light_01_cyan.svg" width="90" height="67">
+<img src="../../_static/images/mdsanima_dev_python_package.webp" width="128" height="67">
 ```
 
 ## EXAMPLE `BLOCK CODE`
 
-Block code in this theme has been changed so that if you want to use a block
-code you can use three examples that differ in color on the front and back
-edges.
+Block code in this theme has been changed so that if you want to use a block code you can use three examples that differ
+in color on the front and back edges.
 
-The `python` block code is rendered like this and is marked with
-{bdg-success-line}`green` color:
+The `python` block code is rendered like this and is marked with {bdg-success-line}`green` color:
 
 ```python
 from mdsanima_dev.emoji import show
 ```
 
-The `shell` block code is rendered like this and is marked with
-{bdg-warning-line}`orange` color:
+The `shell` block code is rendered like this and is marked with {bdg-warning-line}`orange` color:
 
 ```shell
 mdsanima-dev frames-to-timecode --help
 ```
 
-The `markdown` block code is rendered like this and is marked with
-{bdg-primary-line}`blue` color:
+The `markdown` block code is rendered like this and is marked with {bdg-primary-line}`blue` color:
 
 ```markdown
 {octicon}`desktop-download;48px`