Improving the documentation

docs/source/_static/custom.css

@@ -0,0 +1,12 @@
+/* docs/source/_static/custom.css */
+
+/* Style for the custom 'big-text' role */
+.big-text {
+    font-size: 2.5em; /* Adjust the size as needed (e.g., 2em, 3em) */
+    font-weight: bold; /* Make it bold for emphasis */
+    color: #cc0000; /* Optional: Change color for more emphasis */
+    display: block; /* Make it a block element to put it on its own line */
+    margin-top: 1em; /* Add some space above */
+    margin-bottom: 1em; /* Add some space below */
+    text-align: center; /* Center the text */
+}

docs/source/conf.py

@@ -5,7 +5,7 @@ from recommonmark.transform import AutoStructify
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
-
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')))
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -20,7 +20,8 @@ extensions = ['sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
     'sphinx.ext.todo',
-    'recommonmark'
+    'recommonmark',
+    'sphinxcontrib.mermaid'
               ]
 
 templates_path = ['_templates']
@@ -34,6 +35,14 @@ exclude_patterns = []
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
 
+html_css_files = [
+    'custom.css',
+]
+
+rst_prolog = """
+.. role:: bigText
+   :class: big-text
+"""
 
 
 def setup(app):

docs/source/goulag_sort_detailed_explanation.rst

@@ -1,4 +1,106 @@
 .. _goulag_sort_detailed_explanation:
 
 Goulag Sort Explained
-========================
+=====================
+
+The Goulag Sort is a unique sorting algorithm that builds upon the concept of a "Stalin Sort" but avoids data loss. It achieves this by recursively processing the elements that are removed during the initial filtering step and then re-integrating them into the main list.
+
+Let's walk through an example using the list: ``[5, 2, 8, 1, 9, 4]``.
+
+Initial State
+--------------
+
+
+The process begins with the original input list:
+
+.. mermaid::
+
+    graph TD
+        subgraph input_list [ ]
+            direction LR
+            A["5"] --> B["2"] --> C["8"] --> D["1"] --> E["9"] --> F["4"]
+        end
+        style input_list fill:#eee,stroke:#333,stroke-width:2px,rx:5px,ry:5px
+
+Phase 1: Initial Filtering (Stalin Sort Step)
+-----------------------------------------------
+
+
+The algorithm iterates through the list, keeping only elements that are less than or equal to the next element. Elements that are *greater* than the next are "removed".
+
+After this initial filtering pass on ``[5, 2, 8, 1, 9, 4]``:
+
+The main list becomes:
+
+.. mermaid::
+
+    graph TD
+        subgraph input_list [ ]
+            direction LR
+            A["5"] --> C["8"] --> E["9"]
+        end
+        style input_list fill:#eee,stroke:#333,stroke-width:2px,rx:5px,ry:5px
+
+The removed items are collected into a temporary list:
+
+.. mermaid::
+
+    graph TD
+        subgraph temp_list [ ]
+            direction LR
+            B["2"] --> D["1"] --> F["4"]
+        end
+        style temp_list fill:#eee,stroke:#333,stroke-width:2px,rx:5px,ry:5px
+
+Phase 2: Recursive Processing of Removed Items
+------------------------------------------------
+
+
+The Goulag Sort algorithm is then recursively applied to the temporary list of removed items (``[2, 1, 4]``).
+
+Processing ``[2, 1, 4]``:
+- Initial filtering on ``[2, 1, 4]`` removes '1' and '4'.
+- The sub-list becomes ``[2]``.
+- The removed items sub-list is ``[1, 4]``.
+
+The algorithm is then called recursively on ``[1, 4]``:
+- Initial filtering on ``[1, 4]`` removes '4'.
+- The sub-list becomes ``[1]``.
+- The removed items sub-list is ``[4]``.
+
+The algorithm is then called recursively on ``[4]``:
+- This list has a single item, so it's returned as is.
+
+The result of processing ``[1, 4]`` is ``[1]`` (from its sub-list) and ``[4]`` (from its removed list).
+
+The result of processing ``[2, 1, 4]`` is ``[2]`` (from its sub-list) and the processed result of ``[1, 4]`` (which is ``[1]`` and ``[4]``).
+
+After the recursive calls complete, the temporary list ``[2, 1, 4]`` is effectively sorted and becomes:
+
+.. mermaid::
+
+    graph TD
+        subgraph temp_list_processed [ ]
+            direction LR
+            D["1"] --> B["2"] --> F["4"]
+        end
+        style temp_list_processed fill:#eee,stroke:#333,stroke-width:2px,rx:5px,ry:5px
+
+Phase 3: Re-integration
+-------------------------
+
+
+The processed temporary list (``[1, 2, 4]``) is then merged back into the main list (``[5, 8, 9]``) in the correct positions.
+
+The final combined and sorted list is:
+
+.. mermaid::
+
+    graph TD
+        subgraph final_list [ ]
+            direction LR
+            D["1"] --> B["2"] --> F["4"] --> A["5"] --> C["8"] --> E["9"]
+        end
+        style final_list fill:#eee,stroke:#333,stroke-width:2px,rx:5px,ry:5px
+
+This process ensures that all elements are eventuad in their correct sorted positions, avoiding the data loss of a simple Stalin Sort.

docs/source/goulagsort_package.rst

@@ -1,3 +1,5 @@
+.. _goulag_sort_package_reference:
+
 goulag_sort Package
 ===================
 

docs/source/index.rst

@@ -14,6 +14,7 @@ Esta é a documentação da biblioteca Goulag Sort, que implementa um algoritmo
 
    modules
    goulag_sort_detailed_explanation
+   using_goulag_sort
 
 
 

docs/source/using_goulag_sort.rst

@@ -0,0 +1,62 @@
+Using Goulag Sort
+######################
+First and foremost:
+
+:bigText:`WHY???????`
+
+Goulag Sort is not meant to be quick or useful, it is really slow and inefficient.
+
+But if after this warning you wanna use you can...(I ain't your mother)
+
+Installing the Library
+=======================================
+The Library is available to use using pip but is not available on PyPI
+
+Why is not available on PyPI
++++++++++++++++++++++++++++++
+This sorting algorithm is extremely bad and is not meant to be taken seriously, so its not fair to be uploaded.
+
+Installing Via git
+=========================
+
+.. code-block:: bash
+
+    pip install git+https://git.gustavomiranda.xyz/GHMiranda/GoulagSort.git
+
+Using the Library
+==============================
+To use the library firstly you need to import:
+
+.. code-block:: python
+
+    from goulag_sort import send_to_goulag
+
+
+after importing you can call the ``send_to_goulag()`` function
+
+.. code-block:: python
+
+    >>> from goulag_sort import send_to_goulag
+
+    >>> unordered_list = [80,64,14,25,98,1,74,13,10,5]
+    >>> print(unordered_list)
+    [80,64,14,25,98,1,74,13,10,5]
+    >>> send_to_goulag(unordered_list)
+    >>> print(unordered_list)
+    [1,5,10,13,14,25,64,74,80,98]
+
+
+to see the function documentation please refer to:
+:ref:`goulag_sort_package_reference`
+
+
+
+
+
+
+
+
+
+
+
+

goulag_sort/goulagsort.py

@@ -23,7 +23,7 @@ def send_to_goulag(input_list:list)-> list :
         into the middle of the list are then appended to the end of the main list.
 
     For a more detailed step-by-step explanation of the algorithm's flow, please refer to:
-    :ref:`goulag_sort_detailed_explanation`.
+    :ref:`Detailed Explanation <goulag_sort_detailed_explanation>`.
 
     Args:
         input_list (list): The list of numbers to be processed and sorted.