Refactor Documentation

Nicoretti · web-flow · commit c2c38ad2f05d · 2024-05-15T15:12:51.000+02:00
* Replace README.rst with README.md
* Add sphinx-plugins and new sphinx-theme
diff --git a/README.md b/README.md
@@ -0,0 +1,59 @@
+<h1 align="center">Exasol Toolbox</h1>
+
+<p align="center">
+Your one-stop solution for managing all standard tasks and core workflows of your Python project.
+</p>
+
+<p align="center">
+
+<a href="https://github.com/exasol/python-toolbox/actions/workflows/ci.yml">
+    <img src="https://github.com/exasol/python-toolbox/actions/workflows/ci.yml/badge.svg?branch=main" alt="Checks Main">
+</a>
+<a href="https://opensource.org/licenses/MIT">
+    <img src="https://img.shields.io/pypi/l/exasol-toolbox" alt="License">
+</a>
+<a href="https://pypi.org/project/exasol-toolbox/">
+    <img src="https://img.shields.io/pypi/dm/exasol-toolbox" alt="Downloads">
+</a>
+<a href="https://pypi.org/project/exasol-toolbox/">
+    <img src="https://img.shields.io/pypi/pyversions/exasol-toolbox" alt="Supported Python Versions">
+</a>
+<a href="https://pypi.org/project/exasol-toolbox/">
+    <img src="https://img.shields.io/pypi/v/exasol-toolbox" alt="PyPi Package">
+</a>
+</p>
+
+## 🚀 Features
+
+- Centrally managed standard tasks
+  - code formatting & upgrading
+  - linting
+  - type-checking
+  - unit-tests
+  - integration-tests
+  - coverage
+  - documentation
+
+- Centrally manged core workflows
+  - workspace/project verification
+  - build and publish releases
+  - build and publish documentation
+
+- Configurable & Extensible
+  - Project configuration
+  - Event hooks
+
+## 🔌️ Prerequisites
+
+- [Python](https://www.python.org/) >= 3.8
+
+## 💾 Installation
+
+```shell
+pip install exasol-toolbox
+```
+
+## 📚 Documentation
+
+For futher details, checkout the latest [documentation](https://exasol.github.io/python-toolbox/).
+
diff --git a/README.rst b/README.rst
diff --git a/doc/_templates/partials/webfonts.html b/doc/_templates/partials/webfonts.html
diff --git a/doc/api.rst b/doc/api.rst
@@ -1,8 +1,10 @@
-🧰 API Reference
-================
+.. _api:
+
+:octicon:`cpu` API Reference
+=============================
 
 .. figure:: _static/nothing-to-see-here.png
     :alt: nothing to see here
     :target: https://imgflip.com/i/2a7gqa
 
-    source: `imgflip.com <https://imgflip.com/>`_
+    source: `imgflip.com <https://imgflip.com/>`_
diff --git a/doc/changes/changelog.md b/doc/changes/changelog.md
@@ -1,4 +1,4 @@
-# 📝 Changes
+# Changelog
 
 * [unreleased](unreleased.md)
 * [0.9.0](changes_0.9.0.md)
diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md
@@ -2,13 +2,14 @@
 
 🚨 Breaking Changes
 Static callbacks/hooks in the Config object have been removed and replaced with Plugin hooks.
+
 For additional information, refer to [customization](../user_guide/customization.rst) in the user guide.
+## 🐞 Fixed
+* Updated templates for GH workflows to add content of changes file for release letter
 
 ## ✨ Added
 * Implemented plugin support for `pre-` and `post-` integration-tests hooks.
 
 ## 📚 Documentation
 * Added documentation on nox task plugins for users and developers.
-
-## 🐞 Fixed
-* Updated templates for GH workflows to add content of changes file for release letter
+* Updated theme and structure of the documentation.
diff --git a/doc/conf.py b/doc/conf.py
@@ -33,16 +33,14 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
-    "sphinx.ext.autosectionlabel",
     "sphinx_copybutton",
     "myst_parser",
+    "sphinx_design",
 ]
 
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
 # Make sure the target is unique
-autosectionlabel_maxdepth = 1
-autosectionlabel_prefix_document = True
 source_suffix = {
     ".rst": "restructuredtext",
     ".txt": "markdown",
@@ -64,14 +62,16 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "furo"
+html_theme = "shibuya"
 
 # 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_title = "Toolbox"
 html_theme_options = {
-    "light_logo": "light-exasol-logo.svg",
-    "dark_logo": "dark-exasol-logo.svg",
+    "light_logo": "_static/light-exasol-logo.svg",
+    "dark_logo": "_static/dark-exasol-logo.svg",
+    "github_url": "https://github.com/exasol/python-toolbox",
+    "accent_color": "grass",
 }
diff --git a/doc/design.rst b/doc/design.rst
@@ -1,5 +1,7 @@
-📗 Design Document
-==================
+.. _design_document:
+
+Design Document
+===============
 
 Motivation
 ----------
diff --git a/doc/developer_guide/developer_guide.rst b/doc/developer_guide/developer_guide.rst
@@ -1,5 +1,7 @@
-🛠 Developer Guide
-===================
+.. _developer_guide:
+
+:octicon:`tools` Developer Guide
+================================
 
 
 .. toctree::
diff --git a/doc/developer_guide/development.rst b/doc/developer_guide/development.rst
@@ -1,5 +1,5 @@
-🚧 Development - Contributing
-=============================
+Development - Contributing
+==========================
 
 Creating a Release
 ++++++++++++++++++
diff --git a/doc/developer_guide/ideas.rst b/doc/developer_guide/ideas.rst
@@ -1,5 +1,5 @@
-📋 Ideas
---------
+Ideas
+-----
 .. todolist::
 
 - Add commit hooks (version check etc.) for the toolbox itself
diff --git a/doc/developer_guide/plugins.rst b/doc/developer_guide/plugins.rst
@@ -1,5 +1,5 @@
-🔗 Plugin Support
-=================
+Plugin Support
+==============
 
 Our tool currently provides plugin support for Nox tasks. The plugins dedicated to Nox tasks can be found 
 within the :code:`exasol.toolbox.nox.plugins` namespace. To facilitate the implementation of this feature, 
diff --git a/doc/github_actions/github_actions.rst b/doc/github_actions/github_actions.rst
@@ -1,5 +1,7 @@
-🦺 Github Actions
-=================
+.. _github_actions:
+
+:octicon:`play` Github Actions
+===============================
 
 .. toctree::
     :maxdepth: 2
diff --git a/doc/index.rst b/doc/index.rst
@@ -1,12 +1,58 @@
-.. include:: ../README.rst
+Documentation of the Exasol-Toolbox
+-----------------------------------
+
+
+.. grid:: 1 1 3 2
+    :gutter: 2
+    :padding: 0
+    :class-container: surface
+
+    .. grid-item-card:: :octicon:`person` User Guide
+        :link: user_guide
+        :link-type: ref
+
+        Resource for users to understand how to utilize this project and its features.
+
+    .. grid-item-card:: :octicon:`tools` Developer Guide
+        :link: developer_guide
+        :link-type: ref
+
+        Instructions and best practices to help developers contribute to the project and set up their development environment.
+
+    .. grid-item-card:: :octicon:`terminal` Tools
+        :link: tools
+        :link-type: ref
+
+        CLI-Tools which are shipped as part of this project.
+
+    .. grid-item-card:: :octicon:`play` Github Actions
+        :link: github_actions
+        :link-type: ref
+
+        Custom GitHub Actions providing functionality that is commonly needed in our projects.
+
+    .. grid-item-card:: :octicon:`cpu` API Reference
+        :link: api
+        :link-type: ref
+
+        Detailed descriptions, syntax, and usage examples for the API provided by this project.
+
+    .. grid-item-card:: :octicon:`repo` Design Document
+        :link: design_document
+        :link-type: ref
+
+        Document outlining the architectural and design principles and decisions in this project.
+
 
 .. toctree::
    :maxdepth: 1
    :hidden:
 
    user_guide/user_guide
+   developer_guide/developer_guide
    tools
    github_actions/github_actions
    api
-   developer_guide/developer_guide
    changes/changelog
+
+
diff --git a/doc/tools.rst b/doc/tools.rst
@@ -1,5 +1,7 @@
-💻 Tools
-========
+.. _tools:
+
+:octicon:`terminal` Tools
+=========================
 
 The python-toolbox ships with a set of command line tools, whose entry point always is the command :code:`tbx`.
 The commands are structured in a *tree* manner, and help is provided along with the command(s) no matter the nesting.
diff --git a/doc/user_guide/customization.rst b/doc/user_guide/customization.rst
@@ -1,5 +1,5 @@
-🔧 Customization
-================
+Customization
+=============
 
 .. _plugins:
 
diff --git a/doc/user_guide/getting_started.rst b/doc/user_guide/getting_started.rst
@@ -1,5 +1,5 @@
-🚦 Getting Started
-==================
+Getting Started
+===============
 
 Preparing the Project
 ---------------------
diff --git a/doc/user_guide/modules/modules.rst b/doc/user_guide/modules/modules.rst
@@ -1,5 +1,5 @@
-📦 Modules
-==========
+Modules
+=======
 
 .. toctree::
     :maxdepth: 2
diff --git a/doc/user_guide/modules/nox.rst b/doc/user_guide/modules/nox.rst
@@ -1,5 +1,5 @@
 nox
-======
+===
 The nox package contains nox related functionalities like pre defined nox tasks.
 
 .. figure:: ../../_static/nothing-to-see-here.png
diff --git a/doc/user_guide/user_guide.rst b/doc/user_guide/user_guide.rst
@@ -1,5 +1,7 @@
-👤 User Guide
-==============
+.. _user_guide:
+
+:octicon:`person` User Guide
+============================
 
 .. toctree::
     :maxdepth: 2
diff --git a/doc/user_guide/workflows.rst b/doc/user_guide/workflows.rst
@@ -1,5 +1,5 @@
-🏗️ Workflows (CI/CD)
-====================
+Workflows (CI/CD)
+=================
 
 Generate CI & CI/CD workflows
 -----------------------------
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# 📝 Changes`
	`1`	`+# Changelog`
`2`	`2`
`3`	`3`	`* [unreleased](unreleased.md)`
`4`	`4`	`* [0.9.0](changes_0.9.0.md)`