docs(console-script): sphinx documentation for console scripts option

docs(devs): configuration for new theme and some docs string fixes
mdsanima-dev · Feb 23, 2022 · 165671a · 165671a
1 parent e02ed84
commit 165671a
Show file tree

Hide file tree

Showing 4 changed files with 138 additions and 45 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,54 +1,55 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+# Copyritht © 2022 Marcin Różewski MDSANIMA
 
 
-# -- Path setup --------------------------------------------------------------
+"""
+Sphinx configuration file for ``mdsanima-dev`` documentation
+"""
+
+
+# -- Path Setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
-import os
-import sys
-#sys.path.append(os.path.abspath('../..'))
+# import os
+# import sys
+# sys.path.append(os.path.abspath("../.."))
 
 
-# -- Project information -----------------------------------------------------
+# -- Project Information -----------------------------------------------------
 
-project = 'mdsanima-dev'
-copyright = '2021, MDSANIMA'
-author = 'Marcin Rozewski'
-master_doc = 'index'
+project = "mdsanima-dev"
+copyright = "2021-2022, Marcin Różewski MDSANIMAs"
+author = "Marcin Różewski"
+master_doc = "index"
 
 
-# -- General configuration ---------------------------------------------------
+# -- General Configuration ---------------------------------------------------
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
+# sphinx extension modules
 extensions = [
-    'myst_parser',
-    'sphinx_panels',
-    'sphinx_copybutton',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.autosummary',
-    'sphinx.ext.autosectionlabel',
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_panels",
+    "sphinx_inline_tabs",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.extlinks",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
-# Markdown Parser
+# Markdown Parser Options.
 # myst_commonmark_only = True
 # autosectionlabel_prefix_document = True
 source_suffix = {
-    '.rst': 'restructuredtext',
-    '.txt': 'markdown',
-    '.md': 'markdown',
+    ".rst": "restructuredtext",
+    ".txt": "markdown",
+    ".md": "markdown",
 }
 
 # List of patterns, relative to source directory, that match files and
@@ -57,25 +58,47 @@
 exclude_patterns = []
 
 
-# -- Options for HTML output -------------------------------------------------
+# -- Options for HTML Output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-html_theme = 'sphinx_book_theme'
+# The Theme to use for HTML and HTML Help Pages.
+html_theme = "furo"
 html_logo = "_static/icons/ic_mdsanima_08_lng_drp_sdw_c.png"
 html_favicon = "_static/icons/ic_mdsanima_09_smp_w.png"
+
+# Disable the generation of the various indexes
+html_use_modindex = False
+html_use_index = False
 panels_add_bootstrap_css = False
 
 html_theme_options = {
-    "repository_url": "https://github.com/mdsanima-dev/mdsanima-dev",
-    "use_repository_button": True,
-    "use_issues_button": True,
-    "use_edit_page_button": False,
-    "home_page_in_toc": True,
-    "show_navbar_depth": 2,
+    "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": "_blank",
+        },
+    ],
+    "navigation_with_keys": True,
+    "dark_css_variables": {
+        "color-highlight-on-target": "#082542",
+    },
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
+
+
+# -- Options for extlinks ----------------------------------------------------
+
+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/", ""),
+}
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -1,9 +1,17 @@
 # MDSANIMA DEVELOPMENT
 
-Welcome to ``MDSANIMA DEVELOPMENT`` documentation page.
+Welcome to ``MDSANIMA DEVELOPMENT`` documentation site.
 
-This organization is devoted to programming only in the ``Python`` language.
-Sometimes we will add a script written in bash `shell` language.
+```{important}
+This organization mainly deals with ``Python`` programming. Sometimes we also
+code in other languages like ``JavaScript``, ``HTML``, ``Bash Scripting``
+and ``PowerShell``.
+
+We also use the latest technologies Realtime Database, Cloud Servers
+or Machine Learning. We deliver apps and plugins as containers in Docker Compose
+for easy deployment. We know Linux with better security. Every day we learn
+something new.
+```
 
 ```{include} ../../README.md
 ```
@@ -18,12 +26,27 @@ This is all modules include of this package.
     :caption: Python Modules
 
     module_colors
+    module_converts
     module_emoji
     module_table
     module_tools
 ```
 
-## Devs
+## Command Line
+
+This shell console script options allowing you to converting selected function
+directly in command line in the terminal window like `Bash`, `zsh`, `PowerShell`
+and more.
+
+```{eval-rst}
+.. toctree::
+    :maxdepth: 3
+    :caption: Command Line
+
+    shell_converts
+```
+
+## Development
 
 ```{eval-rst}
 .. toctree::

diff --git a/docs/source/module_converts.md b/docs/source/module_converts.md
@@ -0,0 +1,17 @@
+# Module `converts`
+
+```{eval-rst}
+.. automodule:: mdsanima_dev.utils.converts
+```
+
+## Function `frames_to_time_code`
+
+```{eval-rst}
+.. autofunction:: mdsanima_dev.utils.converts.frames_to_time_code
+```
+
+## Function `time_code_to_frames`
+
+```{eval-rst}
+.. autofunction:: mdsanima_dev.utils.converts.time_code_to_frames
+```
diff --git a/docs/source/shell_converts.md b/docs/source/shell_converts.md
@@ -0,0 +1,30 @@
+# Shell `converts`
+
+Converting directly in shell console script on the command line.
+
+```{important}
+This command line options are a wrapper on existing functions and returning
+the same value on calling selected convert method for the appropriate option,
+both shell command line script and python module.
+
+- Python Function
+[``frames_to_time_code``](module_converts.html#function-frames-to-time-code)
+and Console Script
+[``mdsanima-dev-frames-to-time-code``](#command-mdsanima-dev-frames-to-time-code)
+- Python Function
+[``time_code_to_frames``](module_converts.html#function-time-code-to-frames)
+and Console Script
+[``mdsanima-dev-time-code-to-frames``](#command-mdsanima-dev-time-code-to-frames)
+```
+
+## Command `mdsanima-dev-frames-to-time-code`
+
+```{eval-rst}
+.. autofunction:: mdsanima_dev.utils.converts.shell_frames_to_time_code
+```
+
+## Command `mdsanima-dev-time-code-to-frames`
+
+```{eval-rst}
+.. autofunction:: mdsanima_dev.utils.converts.shell_time_code_to_frames
+```