From e825b5996c01cacc01b2a51b3a62c5e1d01a8cc3 Mon Sep 17 00:00:00 2001 From: Gustavo Henrique Santos Souza de Miranda Date: Tue, 20 May 2025 15:39:23 -0300 Subject: [PATCH] Improving the documentation --- docs/source/_static/custom.css | 12 ++ docs/source/conf.py | 13 ++- .../goulag_sort_detailed_explanation.rst | 104 +++++++++++++++++- docs/source/goulagsort_package.rst | 2 + docs/source/index.rst | 1 + docs/source/using_goulag_sort.rst | 62 +++++++++++ goulag_sort/goulagsort.py | 2 +- 7 files changed, 192 insertions(+), 4 deletions(-) create mode 100644 docs/source/_static/custom.css create mode 100644 docs/source/using_goulag_sort.rst diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..ac9bd01 --- /dev/null +++ b/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 */ +} \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 49ddece..fcab22b 100644 --- a/docs/source/conf.py +++ b/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): diff --git a/docs/source/goulag_sort_detailed_explanation.rst b/docs/source/goulag_sort_detailed_explanation.rst index 98945a5..a6af52f 100644 --- a/docs/source/goulag_sort_detailed_explanation.rst +++ b/docs/source/goulag_sort_detailed_explanation.rst @@ -1,4 +1,106 @@ .. _goulag_sort_detailed_explanation: Goulag Sort Explained -======================== \ No newline at end of file +===================== + +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. \ No newline at end of file diff --git a/docs/source/goulagsort_package.rst b/docs/source/goulagsort_package.rst index 2e5c3b5..f2e7e45 100644 --- a/docs/source/goulagsort_package.rst +++ b/docs/source/goulagsort_package.rst @@ -1,3 +1,5 @@ +.. _goulag_sort_package_reference: + goulag_sort Package =================== diff --git a/docs/source/index.rst b/docs/source/index.rst index 02621b9..dcc3d86 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/using_goulag_sort.rst b/docs/source/using_goulag_sort.rst new file mode 100644 index 0000000..cd38f98 --- /dev/null +++ b/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` + + + + + + + + + + + + diff --git a/goulag_sort/goulagsort.py b/goulag_sort/goulagsort.py index d5087a8..5ef91b7 100644 --- a/goulag_sort/goulagsort.py +++ b/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 `. Args: input_list (list): The list of numbers to be processed and sorted.