Merge pull request #2 from lias-laboratory/enhance-docs

Enhanced Documentation

Author: quentinhaenn

README.md

@@ -1,8 +1,8 @@
 <p align="center">
-<a href="https://github.com/lias-laboratory/radius_clustering/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/github/license/lias-laboratory/radius-clustering"></a>
+<a href="https://github.com/lias-laboratory/radius_clustering/blob/main/LICENSE"><img alt="License: GPLv3" src="https://img.shields.io/github/license/lias-laboratory/radius_clustering"></a>
 <a href="https://pypi.org/project/radius-clustering/"><img alt="PyPI" src="https://img.shields.io/pypi/v/radius-clustering"></a>
 <a href="https://docs.astral.sh/ruff/"><img alt="Code style: Ruff" src="https://img.shields.io/badge/style-ruff-41B5BE?style=flat"></a>
-<a><img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/lias-laboratory/radius-clustering/sphinx.yml?label=Doc%20Building"></a>
+<a href="https://lias-laboratory.github.io/radius_clustering/"><img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/lias-laboratory/radius_clustering/sphinx.yml?label=Doc%20Building"></a>
 <a><img alt="Python version supported" src="https://img.shields.io/pypi/pyversions/radius-clustering"></a>
 
 </p>

docs/source/conf.py

@@ -8,7 +8,9 @@
 
 import os
 import sys
+from pathlib import Path
 
+sys.path.insert(0, os.path.abspath("."))
 sys.path.insert(0, os.path.abspath("../.."))
 
 project = "Radius Clustering"
@@ -25,6 +27,7 @@
     "sphinx.ext.viewcode",
     "sphinx-prompt",
     "sphinx.ext.napoleon",
+    "sphinxcontrib.sass",
     "sphinx_remove_toctrees",
     "sphinxcontrib.email",
     "sphinx_gallery.gen_gallery",
@@ -82,6 +85,17 @@
     "footer_end": [],
 }
 
+# Compile scss files into css files using sphinxcontrib-sass
+sass_src_dir, sass_out_dir = "scss", "_static/styles"
+sass_targets = {
+    f"{file.stem}.scss": f"{file.stem}.css"
+    for file in Path(sass_src_dir).glob("*.scss")
+}
+
+html_static_path = ["_static"]
+# Additional CSS files, should be subset of the values of `sass_targets`
+html_css_files = ["styles/custom.css"]
+
 sg_examples_dir = "../../examples"
 sg_gallery_dir = "auto_examples"
 sphinx_gallery_conf = {

docs/source/details.rst

@@ -118,6 +118,4 @@ Key insights:
 
 .. note:: Since the publication of the paper, the Radius Clustering package has been improved and optimized. The results presented here are based on the initial version of the package. For the latest results, please refer to the documentation or the source code.
 
-References
-==========
 

docs/source/installation.rst

@@ -10,6 +10,12 @@ There are different ways to install Radius Clustering:
 
 * :ref:`From the source <installation-source>`. This is best for users who want the latest features and are comfortable building from source. This is also needed if you want to contribute to the project.
 
+.. warning::
+
+    Radius Clustering is currently not available on PyPI, pending the organization acceptance on PyPI. You can install the package from the source by following the :ref:`instructions <installation-source>`.
+    Please notice that the compilation stage require a C and C++ compiler toolchain to be installed on your system.
+
+
 .. _installation-pypi:
 
 Installing from PyPI
@@ -27,20 +33,18 @@ Installing from PyPI
       .install-instructions .sd-tab-set.tabs-os::before {
         content: "Operating System";
       }
-
-      .install-instructions .sd-tab-set.tabs-package-manager::before {
-        content: "Package Manager";
-      }
     }
   </style>
 
 .. div:: install-instructions
 
   .. tab-set::
     :class: tabs-os
+    :sync-group: os
 
     .. tab-item:: Windows
       :class-label: tab-4
+      :sync: windows
 
           Install the 64-bit version of Python 3, for instance from the
           `official website <https://www.python.org/downloads/windows/>`__.
@@ -65,7 +69,7 @@ Installing from PyPI
 
     .. tab-item:: MacOS
       :class-label: tab-4
-
+      :sync: macos
 
           Install Python 3 using `homebrew <https://brew.sh/>`_ (`brew install python`)
           or by manually installing the package from the `official website
@@ -91,6 +95,7 @@ Installing from PyPI
 
     .. tab-item:: Linux
       :class-label: tab-4
+      :sync: linux
 
           Python 3 is usually installed by default on most Linux distributions. To
           check if you have it installed, try:
@@ -143,12 +148,84 @@ a Raspberry Pi).
 Installing from the source
 --------------------------
 
-To install Radius Clustering from the source, you need to clone the repository and
+Compiler Requirements
+~~~~~~~~~~~~~~~~~~~~~
+
+To install Radius Clustering from the source, you need to have a C and C++ compiler and their respective toolchains installed on your system, depending on your operating system.
+
+.. raw:: html
+
+  <style>
+    /* Show caption on large screens */
+    @media screen and (min-width: 960px) {
+      .install-instructions .sd-tab-set {
+        --tab-caption-width: 20%;
+      }
+
+      .install-instructions .sd-tab-set.tabs-os::before {
+        content: "Operating System";
+      }
+    }
+  </style>
+
+.. div:: install-instructions
+
+  .. tab-set::
+    :class: tabs-os
+    :sync-group: os
+
+    .. tab-item:: Windows
+      :class-label: tab-4
+      :sync: windows
+
+          Install the correct version of Microsoft Visual C++ Build Tools for your Python version from the `official website <https://visualstudio.microsoft.com/visual-cpp-build-tools/>`__.
+
+          In Build Tools, install C++ toolchain. Ensure that it is added to the system PATH.
+          You are now ready to install Radius Clustering from source.
+
+    .. tab-item:: MacOS
+      :class-label: tab-4
+      :sync: macos
+
+        Normally, you should have the necessary tools installed on your system as it comes with Xcode Command Line Tools, which is included when you first install Homebrew or Xcode.
+           To check if you have the necessary tools installed, try:
+
+        .. prompt:: bash
+
+             gcc --version
+             g++ --version
+
+        If you don't have the necessary tools installed, you can install them directly from the App Store by getting Xcode. You may also be interested in installing Homebrew. See this `tutorial <https://www.moncefbelyamani.com/how-to-install-xcode-with-homebrew/>`__ for more information.
+
+    .. tab-item:: Linux
+      :class-label: tab-4
+      :sync: linux
+
+            Normally, you should have the necessary tools installed on your system. To check if you have the necessary tools installed, try:
+
+            .. prompt:: bash
+
+                gcc --version
+                g++ --version
+
+            If you don't have the necessary tools installed, you can install them using your distribution's package manager. For instance, on Ubuntu, you can install them by running:
+
+            .. prompt:: bash
+
+                sudo apt-get update
+                sudo apt-get install build-essential
+
+
+Installing Radius Clustering
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now you have installed compilers toolchains requirements, you can build and install `radius-clustering` from the sources. You need to clone the repository and
 install the package using the following commands:
 
 .. prompt:: bash
 
-  cd /path/to/your/folder
+  git clone [email protected]:lias-laboratory/radius_clustering.git # clone the repository
+  cd radius_clustering
   python -m venv rad-env
   source rad-env/bin/activate  # activate
   python -m pip install .

docs/source/scss/custom.scss

@@ -0,0 +1,47 @@
+/* Tabs (sphinx-design) */
+
+.sd-tab-set {
+  --tab-caption-width: 0%; // No tab caption by default
+  margin-top: 1.5rem;
+
+  &::before {
+    // Set `content` for tab caption
+    width: var(--tab-caption-width);
+    display: flex;
+    align-items: center;
+    font-weight: bold;
+  }
+
+  .sd-tab-content {
+    padding: 0.5rem 0 0 0 !important;
+    background-color: transparent !important;
+    border: none !important;
+
+    blockquote {
+      background-color: transparent !important;
+      border: none !important;
+    }
+
+    > p:first-child {
+      margin-top: 1rem !important;
+    }
+  }
+
+  > label.sd-tab-label {
+    margin: 0 3px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 5px !important;
+
+
+    &.tab-4 {
+      width: calc((100% - var(--tab-caption-width)) / 3 - 6px) !important;
+    }
+  }
+
+  > input:checked + label.sd-tab-label {
+    transform: unset;
+    border: 2px solid var(--pst-color-primary);
+  }
+}

pyproject.toml

@@ -61,6 +61,7 @@ dev = [
     "sphinx-remove-toctrees>=1.0.0",
     "sphinx-prompt>=1.9.0",
     "sphinx_design>=0.6.1",
+    "sphinxcontrib.sass >= 0.3.4",
 ]
 
 doc = [
@@ -72,6 +73,7 @@ doc = [
     "sphinx-remove-toctrees>=1.0.0",
     "sphinx-prompt>=1.9.0",
     "sphinx_design>=0.6.1",
+    "sphinxcontrib.sass >= 0.3.4",
 ]
 
 [tool.setuptools]