Updated project documentation to use the Useblocks theme customization.

demo/doc-requirements.txt

@@ -1,3 +1,3 @@
 sphinx==5.1.1
 sphinxcontrib-plantuml==0.24
-sphinx-needs==1.0.2
+sphinx-needs

docs/changelog.rst

@@ -5,6 +5,7 @@ Release 1.6
 -----------
 :released: 20.01.2023
 
+* **Improvement**: Updated project documentation to use the Useblocks theme customization.
 * **Bugfix** [#60] Fix TOC hrefs for sections that use file title anchors.
 * **Enhancement** [#62] Added config option to build PDFs with the weasyprint Python API instead of the binary. 
 

docs/conf.py

@@ -9,6 +9,11 @@
 import os
 import sphinx
 import datetime
+import sys
+
+sys.path.append(os.path.abspath("."))  # Example if `ub_theme` folder is in the same folder as the `conf.py` file
+
+from ub_theme.conf import ub_html_theme_options
 
 project = 'Sphinx-SimplePDF'
 copyright = '2022, team useblocks'
@@ -20,13 +25,14 @@
 extensions = [
     'sphinx_simplepdf',
     'sphinxcontrib.plantuml',
-    'sphinxcontrib.needs',
+    'sphinx_needs',
+    'sphinx_immaterial',
     'sphinx_copybutton',
 ]
 
 version = "1.6.0"
 
-templates_path = ['_templates']
+templates_path = ["_templates", "ub_theme/templates"]
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 plantuml_output_format = "svg_img"
@@ -44,27 +50,29 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-#html_theme = 'sphinx_immaterial'
-html_theme = 'alabaster'
-#html_theme = 'sphinx_needs_pdf'
-html_static_path = ['_static']
-
-html_theme_options = {
-    'github_user': 'useblocks',
-    'github_repo': 'sphinx-simplepdf',
-    'fixed_sidebar': True,
-    'github_banner': True,
-    'github_button': False,
+html_theme = 'sphinx_immaterial'
+html_title = 'Sphinx-SimplePDF'
+# html_theme = 'alabaster'
+# html_theme = 'sphinx_needs_pdf'
+
+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/sphinx-simplepdf",
+    "repo_name": "sphinx-simplepdf",
+    "repo_type": "github",
 }
+html_theme_options.update(other_options)
 
 html_context = {
     'docs_scope': 'external',
-    'cover_logo_title': '',
     'cover_meta_data': 'The simple PDF builder for Sphinx.',
-    'cover_footer': f'Build: {datetime.datetime.now().strftime("%d.%m.%Y")}<br>'
-                    f'Maintained by <a href="https://useblocks.com">team useblocks</a>',
 }
 
+html_static_path = ["_static", "ub_theme/css", "ub_theme/js"]
+html_css_files = ["ub-theme.css"]
+html_js_files = ["ub-theme.js"]
+
 
 def setup_jquery(app, exception):
     """
@@ -86,4 +94,3 @@ def setup_jquery(app, exception):
             }
         ))
         app.config.html_js_files = html_js_files
-

docs/doc-requirements.txt

@@ -1,4 +1,5 @@
 sphinx==5.1.1
 sphinxcontrib-plantuml==0.24
-sphinxcontrib-needs==0.7.8
-sphinx-copybutton
+sphinx-needs
+sphinx-copybutton
+sphinx-immaterial

docs/index.rst

@@ -10,10 +10,9 @@ This Sphinx extension provides an easy way to build beautiful PDFs based on CSS
 
 It contains:
 
- * A PDF specific, CSS based Sphinx theme: ``sphinx_simplepdf``.
- * A Sphinx builder, called ``simplepdf``
- * :ref:`Directives <directives>` to
-
+* A PDF specific, CSS based Sphinx theme: ``sphinx_simplepdf``.
+* A Sphinx builder, called ``simplepdf``
+* :ref:`Directives <directives>` 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

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/

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.