` to
* control different structures and content for ``HTML`` and ``PDF`` builds.
* embed PDF inside HTML views.
@@ -90,7 +89,6 @@ Showcase
.. toctree::
- :caption: Content
:maxdepth: 3
installation
@@ -99,6 +97,6 @@ Showcase
directives
css
tech_details
- examples/index
+ examples/sphinx_needs
changelog
license
\ No newline at end of file
diff --git a/docs/ub_theme/.gitignore b/docs/ub_theme/.gitignore
new file mode 100644
index 0000000..2b710ed
--- /dev/null
+++ b/docs/ub_theme/.gitignore
@@ -0,0 +1,129 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+# Usually these files are written by a python script from a template
+# before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+# However, in case of collaboration, if having platform-specific dependencies or dependencies
+# having no cross-platform support, pipenv may install dependencies that don't work, or not
+# install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.idea/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
diff --git a/docs/ub_theme/README.md b/docs/ub_theme/README.md
new file mode 100644
index 0000000..91e0c47
--- /dev/null
+++ b/docs/ub_theme/README.md
@@ -0,0 +1,102 @@
+# useblocks-theme
+This repository contains the theme for all Useblock documentation sites.
+
+> **NOTE:**
+> - Useblocks uses the Sphinx-Immaterial theme so ensure that the theme is already installed and applied.
+> - Install `sphinx_immaterial` by running this command: `pip install sphinx-immaterial`.
+> - Then activate the theme by adding it to the `extension` variable under **conf.py**: `extensions = ["sphinx_immaterial"]`
+> - And change the `html_theme` variable to `html_theme = "sphinx_immaterial"`
+
+## Installation
+To install the files from this repository, you must have [Git](https://git-scm.com) installed.
+
+* Change directory to your preferred docs working directory
+ ```bash
+ cd docs
+ ```
+* Download the files from the repository:
+ ```bash
+ git clone https://github.com/useblocks/ub_theme.git
+ ```
+* Delete both the **.git** hidden directory and **.gitignore** hidden file from the **ub_theme** folder.
+
+## Configuration
+
+You must configure the following in the **conf.py** file of the Sphinx documentation project.
+
+* In order to import the **ub_theme** package, Python searches through the directories on `sys.path` looking for the package subdirectory.
+ * Add the parent path of the **ub_theme** folder to `sys.path`.
+ ```python
+ import os
+ import sys
+ sys.path.append(os.path.abspath(".")) # Example if `ub_theme` folder is in the same folder as the `conf.py` file
+ ```
+* Add the `ub_html_theme_options` to your **conf.py**:
+ * Import the theme options for Useblocks.
+ ```python
+ from ub_theme.conf import ub_html_theme_options
+ ```
+ * Set it as the value for the `ub_html_theme_options` variable.
+ ```python
+ html_theme_options = ub_html_theme_options
+ ```
+* Add the custom template changes folder to the `templates_path` variable.
+ ```python
+ templates_path = ["_templates", "ub_theme/templates"]
+ ```
+* Add custom CSS changes:
+ * Add the folder containing the CSS files to the `html_static_path` variable.
+ ```python
+ html_static_path = ["ub_theme/css"]
+ ```
+ * Add the custom CSS files to the `html_css_files` variable.
+ ```python
+ html_css_files = ["ub-theme.css"]
+ ```
+* Add custom JS changes:
+ * Add the folder containing the JS files to the `html_static_path` variable.
+ ```python
+ html_static_path = ["ub_theme/js"]
+ ```
+ * Add the custom JS files to the `html_js_files` variable.
+ ```python
+ html_js_files = ["ub-theme.js"]
+ ```
+
+The final configuration should look like below:
+```python
+import os
+import sys
+
+sys.path.append(os.path.abspath("."))
+
+from ub_theme.conf import ub_html_theme_options
+
+extensions = [
+ "sphinx_immaterial",
+]
+
+templates_path = ["_templates", "ub_theme/templates"]
+
+html_theme = "sphinx_immaterial"
+html_theme_options = ub_html_theme_options
+
+# You can add other Sphinx-Immaterial theme options like below
+other_options = {
+ "repo_url": "https://github.com/useblocks/ub_theme",
+ "repo_name": "useblocks-theme",
+ "repo_type": "github",
+}
+html_theme_options.update(other_options)
+
+html_static_path = ["_static", "ub_theme/css", "ub_theme/js"]
+html_css_files = ["ub-theme.css"]
+html_js_files = ["ub-theme.js"]
+
+```
+
+## Changelog
+
+* 23.01.2023 - Updated CSS for theme, changelog and conf.py
+* 13.01.2023 - Updated CSS stylesheets and docs on how to apply the theme customization.
+* 28.12.2022 - Setup and added the initial Useblocks theme codes.
diff --git a/docs/ub_theme/__init__.py b/docs/ub_theme/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/docs/ub_theme/conf.py b/docs/ub_theme/conf.py
new file mode 100644
index 0000000..7946575
--- /dev/null
+++ b/docs/ub_theme/conf.py
@@ -0,0 +1,41 @@
+ub_html_theme_options = {
+ "icon": {
+ "repo": "fontawesome/brands/github",
+ },
+ "font": {
+ "code": "JetBrains Mono",
+ "text": "Recursive"
+ },
+ "globaltoc_collapse": True,
+ "features": [
+ "navigation.top",
+ "search.share",
+ "navigation.tracking",
+ "toc.follow",
+ "content.tabs.link"
+ ],
+ "palette": [
+ {
+ "media": "(prefers-color-scheme: light)",
+ "scheme": "default",
+ "primary": "yellow",
+ "accent": "yellow",
+ "toggle": {
+ "icon": "material/weather-night",
+ "name": "Switch to dark mode",
+ },
+ },
+ {
+ "media": "(prefers-color-scheme: dark)",
+ "scheme": "slate",
+ "primary": "yellow",
+ "accent": "yellow",
+ "toggle": {
+ "icon": "material/weather-sunny",
+ "name": "Switch to light mode",
+ },
+ },
+ ],
+ "toc_title_is_page_title": True,
+ "toc_title": "Contents",
+}
diff --git a/docs/ub_theme/css/ub-theme.css b/docs/ub_theme/css/ub-theme.css
new file mode 100644
index 0000000..53b1d1f
--- /dev/null
+++ b/docs/ub_theme/css/ub-theme.css
@@ -0,0 +1,229 @@
+/* @import url('https://fonts.googleapis.com/css2?family=Recursive:wght@300;400&display=swap'); */
+
+:root > * {
+ --md-primary-fg-color: #FFCC00;
+ --md-primary-fg-color--light: #ffeb9b;
+ --md-primary-fg-color--dark: #957700;
+}
+
+/* Nav */
+.md-tabs {
+ background-color: #000;
+ color: #fff;
+ text-align: center;
+}
+.md-tabs__item span {
+ font-size: medium;
+ font-weight: 600;
+}
+.md-header {
+ background-color: var(--md-primary-fg-color);
+ color: #000;
+}
+.md-top {
+ top: 70px!important;
+}
+
+/*Light Mode*/
+[data-md-color-scheme=default]{
+--md-default-fg-color--light: #0000008a;
+--img-filter: none;
+}
+
+/*Night Mode*/
+[data-md-color-scheme=slate]{
+--md-default-fg-color--light: #d2d7f9;
+--img-filter: brightness(0) invert(1);
+}
+.md-typeset h1{
+ color: var(--md-default-fg-color--light);
+}
+
+td.needs_title {
+ font-weight: bold;
+}
+.md-typeset pre, pre {
+ overflow-x: auto;
+}
+div.wy-table-responsive{
+ width: 100% !important;
+}
+.underline{
+ text-decoration: underline;
+}
+figure[id^="needflow-"] {
+ overflow-x: auto;
+}
+
+
+/*Remove READTHEDOCS version badge*/
+.injected {
+ display: none !important;
+}
+div.need_container {
+ overflow-x: auto;
+}
+table.need, .md-typeset table.data:not(.plain) {
+ display: table !important;
+ width: 100% !important;
+}
+table {
+ border: 1px solid #e1e4e5 !important;
+}
+tbody tr td {
+ font-size: medium !important;
+}
+img.needs_image, img.sn_collapse_img {
+ filter: var(--img-filter);
+}
+
+/* Sphinx-Immaterial */
+
+body,
+input {
+ font-size: 18px !important;
+ font-weight: 400;
+ line-height: 1.5 !important;
+}
+
+.md-typeset, .md-nav, .md-typeset table:not([class]),
+ .md-typeset table.data:not(.plain){
+ font-size: 18px !important;
+ line-height: 1.5 !important;
+}
+
+.md-typeset :is(.admonition,details) {
+ font-size: 14px;
+}
+
+h1, h2, h3 {
+ font-weight: 500 !important;
+ line-height: 1.4 !important;
+}
+
+h1:not([class="md-search-result__title"]) {
+ font-size: 34px !important;
+ margin-bottom: 20px !important;
+}
+
+h2 {
+ font-size: 28px !important;
+ margin-bottom: 10px !important;
+}
+
+h3 {
+ font-size: 24px !important;
+ margin-bottom: 10px !important;
+}
+
+/* datatables */
+.dataTables_filter input {
+ border: 1px solid var(--md-typeset-color);
+ margin-bottom: 10px;
+ background-color: transparent;
+}
+
+.border {
+ border: 1px solid var(--md-typeset-color);
+}
+
+table.dataTable tbody tr {
+ background-color: transparent;
+}
+/*
+table.dataTable tbody tr {
+ background-color: transparent !important;
+}
+*/
+.dataTables_wrapper .dataTables_length, .dataTables_wrapper .dataTables_filter, .dataTables_wrapper .dataTables_info, .dataTables_wrapper .dataTables_processing, .dataTables_wrapper .dataTables_paginate {
+ color: var(--md-typeset-color) !important;
+}
+
+.dataTables_wrapper .dataTables_paginate a.paginate_button, .dataTables_wrapper .dataTables_paginate a.paginate_button.current {
+ color: var(--md-typeset-color) !important;
+}
+
+div.dataTables_info {
+ margin-top: 0 !important;
+}
+
+div.dt-button-info{
+ bottom:0.8rem;
+ left:1rem;
+ top:initial;
+ left:initial;
+ width:initial;
+ background-color:#e9ebfc;
+ border: 1px solid var(--md-typeset-color);
+ box-shadow:0 0.2rem 0.5rem rgba(0,0,0,.4),0 0 0.05rem rgba(0,0,0,.35);
+ border-radius:0.1rem;
+ text-align:left;
+ color: #2e303e;
+ min-width:11.1rem;
+ padding: 0.4rem 0.6rem;
+ pointer-events: none;
+ margin:0;
+}
+div.dt-button-info h2{
+ display:none;
+}
+div.dt-button-info>div{
+ padding:2px;
+ font-size: 18px!important;
+ color: #2e303e;
+}
+
+table tbody tr:hover {
+ background-color: rgb(147 147 147 / 10%) !important;
+ box-shadow: 0 .05rem 0 var(--md-default-bg-color) inset !important;
+}
+
+button.dt-button:hover:not(.disabled), div.dt-button:hover:not(.disabled), a.dt-button:hover:not(.disabled) {
+ color: #000;
+}
+
+.dataTables_wrapper .dataTables_filter {
+ float: left !important;
+ margin-left: 1% !important;
+}
+
+div.dt-buttons {
+ margin-left: 1% !important;
+}
+
+.dataTables_wrapper .dataTables_filter input {
+ max-width: 100px !important;
+}
+@media screen and (max-width: 640px){
+ .dataTables_wrapper .dataTables_filter {
+ float: none !important;
+ text-align: center !important;
+ }
+
+ .dataTables_wrapper .dataTables_filter input {
+ max-width: inherit !important;
+ }
+}
+
+div.dt-button-collection button.dt-button.active:not(.disabled) {
+ color: #000 !important;
+ border: 1px solid #000 !important;
+}
+
+table.NEEDS_DATATABLES, table.NEEDS_TABLE{
+ max-width: inherit;
+ width: inherit;
+}
+
+.md-header__button.md-logo :is(img, png) {
+ height: 2.2rem !important;
+}
+
+@media screen and (min-width: 76.1875em){
+ .md-nav__current-toc {
+ display: none!important;
+ }
+}
+details.sd-dropdown .sd-summary-up, details.sd-dropdown .sd-summary-down {
+ display: none;
+}
\ No newline at end of file
diff --git a/docs/ub_theme/js/ub-theme.js b/docs/ub_theme/js/ub-theme.js
new file mode 100644
index 0000000..dad2c28
--- /dev/null
+++ b/docs/ub_theme/js/ub-theme.js
@@ -0,0 +1,3 @@
+$(document).ready(function() {
+ $("table.NEEDS_DATATABLES, table.NEEDS_TABLE").wrap("");
+});
\ No newline at end of file
diff --git a/docs/ub_theme/templates/layout.html b/docs/ub_theme/templates/layout.html
new file mode 100644
index 0000000..60f547b
--- /dev/null
+++ b/docs/ub_theme/templates/layout.html
@@ -0,0 +1,6 @@
+{# Import the theme's layout. #}
+{% extends '!layout.html' %}
+
+{%- block extrahead %}
+ {{ super() }}
+{%- endblock %}
diff --git a/docs/ub_theme/templates/partials/copyright.html b/docs/ub_theme/templates/partials/copyright.html
new file mode 100644
index 0000000..7b50ba2
--- /dev/null
+++ b/docs/ub_theme/templates/partials/copyright.html
@@ -0,0 +1,24 @@
+{#-
+ This file was automatically generated - do not edit
+-#}
+
+ {% if show_copyright %}
+
+ {% endif %}
+ {%- if show_sphinx %}
+ {%- endif %}
+ {{ rendered_extracopyright }}
+
+