Merge pull request #9 from olilag/documentation

Documentation

.gitignore

@@ -80,6 +80,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/generated
 
 # PyBuilder
 .pybuilder/
@@ -250,3 +251,5 @@ fabric.properties
 .idea/caches/build_file_checksums.ser
 
 .vscode
+
+!.readthedocs.yaml

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  commands:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uvx install hatch
+    - hatch shell docs
+    - sphinx-build -T -b html -d docs/_build/doctrees docs $READTHEDOCS_OUTPUT/html

docs/api/dictionary.rst

@@ -0,0 +1,13 @@
+dictionary
+==========
+
+Tu sa nachádza trieda :py:class:`Dictionary`, ktorá automaticky stiahne zvolený slovník
+a vráti cestu k danému súboru.
+
+.. code-block:: python
+
+    from susi_lib import Dictionary
+    # takto sa importuje trieda Dictionary
+
+.. automodule:: susi_lib.dictionary
+    :members:

docs/api/finder.rst

@@ -0,0 +1,16 @@
+finder
+=======
+
+Tu sa nachádza jediná trieda :py:class:`Finder`. Slúži na hľadanie slov, ktoré spĺňajú nejakú zadanú funkciu.
+
+.. code-block:: python
+
+    from susi_lib import Finder
+    # takto sa importuje trieda Finder
+
+.. automodule:: susi_lib.finder
+    :members:
+
+**Príklad**
+
+.. literalinclude:: /../examples/finder_example.py

docs/api/functions.rst

@@ -0,0 +1,13 @@
+functions
+=========
+
+Tu sa nachádzajú funkcie, ktoré sa vedia hodiť počas hladanie hesiel
+a netreba ich tým pádom nanovo programovať.
+
+.. code-block:: python
+
+    from susi_lib.functions import *
+    # takto sa importujú všetky funkcie odtiaľto
+
+.. automodule:: susi_lib.functions.functions
+    :members:

docs/api/index.rst

@@ -0,0 +1,15 @@
+API reference
+=============
+
+Tu sa nachádza bližší popis jednotlivých funkcionalít. Všetky popisy sú automaticky vygenerované zo zdrojového kódu.
+
+Obsah:
+
+.. toctree::
+    :maxdepth: 2
+
+    types
+    functions
+    finder
+    regex
+    dictionary

docs/api/regex.rst

@@ -0,0 +1,14 @@
+regex
+=====
+
+Tu je trieda :py:class:`RegEx`, ktorá obalí regulárny výraz a dáta, na ktorých má byť vykonaný.
+Tiež je tu funkcia :py:func:`create_regex`, ktorá vytvorí z jej argumentov inštanciu
+:py:class:`RegEx` pre výraz, ktorý je daný jej argumentami.
+
+.. code-block:: python
+
+    from susi_lib import RegEx, create_regex, Selection
+    # takto sa importujú všetky funkcie odtiaľto
+
+.. automodule:: susi_lib.regex
+    :members:

docs/api/types.rst

@@ -0,0 +1,32 @@
+types
+=====
+
+.. code-block:: python
+
+    from susi_lib.types import *
+    # takto sa importujú všetky triedy odtiaľto
+
+**Braille**
+
+.. automodule:: susi_lib.types.braille
+    :members:
+
+**Semaphore**
+
+.. automodule:: susi_lib.types.semaphore
+    :members:
+
+**Morse**
+
+.. automodule:: susi_lib.types.morse
+    :members:
+
+**NumberSystems**
+
+.. automodule:: susi_lib.types.number_systems
+    :members:
+
+**Symbols**
+
+.. automodule:: susi_lib.types.symbols
+    :members:

docs/applications/index.rst

@@ -0,0 +1,9 @@
+Aplikácie
+=========
+
+Tu je zoznam aplikácii, ktoré sú súčasťou balíčku.
+
+.. toctree::
+    :titlesonly:
+
+    word-finder

docs/applications/word-finder.rst

@@ -0,0 +1,79 @@
+Word Finder
+===========
+
+Tento program slúži na hľadania slov v nejakom slovníku, ak máme nejaké obmedzenia na písmená na konkrétnych pozíciach.
+
+Otvor si príkazový riadok (na windowse radšej PowerShell):
+
+.. code-block:: console
+
+    $ susi-word-finder -h   # zobrazí nápovedu
+    $ susi-word-finder -i sample_file.txt -w abcde  # nájde všetky slová dlhé 5 obsahujúce iba abcde, ktoré sú v súbore sample_file.txt
+
+Možnosti
+--------
+
+Program vie meniť svoje správanie podľa toho, čo napíšeš za ``susi-word-finder``. Nižšie je popis všetkých možností:
+
+.. list-table::
+    :widths: 50 50
+    :header-rows: 1
+
+    * - Možnosť
+      - Popis
+    * - ``-h/--help``
+      - zobrazí nápovedu
+    * - ``-i/--input-file``
+      - tu nasleduje cesta k textovému súboru, v ktorom chceme hľadať alebo skratku slovníku :any:`Dictionary`
+    * - ``-w/--word-length``
+      - nasleduje číslo, aké dlhé slová má hľadať alebo rozpätie ``x-y``, ktoré znamená, že vyhľadá všetky slová dlhé ``x`` až ``y``
+
+Číslo pri ``-w/--word-length`` sa použije hlavne vtedy, ak nasleduje iba
+jeden argument. Ak sa ``-w/--word-length`` nepoužije, dĺžka slova sa určí
+podľa počtu argumentov. Pri použití rozpätia musí nasledovať iba jedna skupina písmen.
+
+Argumenty
+---------
+
+Po možnostiach nasledujú argumenty. Ak sa určí dĺžka hľadaného slova cez
+``-w/--word-length``, stačí ako ďalší argument napísať množinu písmen,
+ktoré chceme aby heslo obsahovalo. Program potom nájde všetky slová v
+zdrojovom súbore, ktoré sú tvorené iba zadanými písmenami.
+
+Ak dĺžku slova neurčíme, tak sa dĺžka slova určí podľa počtu argumentov.
+Každý argument reprezentuje písmená, ktoré majú v hľadanom slove na
+danom mieste. argumenty sú oddelené medzerou.
+
+.. list-table::
+    :widths: 50 50
+    :header-rows: 1
+
+    * - Znak
+      - Popis
+    * - ``^``
+      - ak použijeme tento znak, tak programu povieme, že nemá použiť zadanú množinu písmen
+    * - ``a-z``
+      - skrátený zápis množiny tvorenej písmenami a až z, môžeme použiť iné písmená ako a a z
+    * - ``.``
+      - reprezentuje ľubovoľný znak
+
+Príklady
+--------
+
+.. code-block:: console
+
+    $ susi-word-finder -i podstatne_mena_ascii.txt -w 5 abc . . ^a-f .
+
+
+Zo súboru ``podstatne_mena_ascii.txt`` vyberie všetky ``5`` písmenové slová,
+ktoré majú na prvej pozícii niektoré z písmen ``abc``, na druhej a tretej
+pozícii môžu byť ľubovoľné znaku, na štvrtej pozícii nemôžu byť písmená
+``a-f`` (a až f) a na poslednej pozícii môže byť ľubovoľné písmeno.
+
+.. code-block:: console
+
+    $ susi-word-finder -i PM_a -w 7 abcde
+
+
+Zo súboru ``podstatne_mena_ascii.txt`` vyberie všetky ``7`` písmenové slová,
+ktoré sú tvorené iba písmenami ``abcde``.

docs/conf.py

@@ -0,0 +1,49 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import os
+import re
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "susi-lib"
+copyright = "2024, Oliver Lago"
+author = "Oliver Lago"
+release = re.sub("^v", "", os.popen("git describe --tags").read().strip())
+version = release
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_last_updated_by_git",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx_rtd_theme",
+    "sphinx_git",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+language = "en"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_context = {
+    "current_version": version,
+}
+
+pygments_style = "sphinx"
+
+autodoc_typehints = "both"
+autodoc_typehints_format = "short"
+autoclass_content = "both"
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

docs/feedback.rst

@@ -0,0 +1,21 @@
+Feedback
+========
+
+Budem rád za feedback k ľubovoľnej časti. Najlepšie mi napíš dm na Slack alebo ak vieš,
+tak rovno vyrob issue na `GitHube <https://github.com/olilag/susi-lib/issues>`_ s rozumným popisom chyby
+alebo novej feature.
+
+Ak si myslíš, že danú vec vieš sám opraviť, tak to sprav v novej branchi a vyrob pull request.
+
+Na vývoj používam `hatch <https://hatch.pypa.io/latest/>`_, pre vytvorenie dev environmentu spusti:
+
+.. code-block:: console
+
+    $ hatch shell dev
+
+
+Pre spustenie testov zadaj:
+
+.. code-block:: console
+
+    $ hatch test

docs/index.rst

@@ -0,0 +1,18 @@
+susi-lib
+========
+
+Obsah:
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   usage
+   applications/index
+   api/index
+   feedback
+
+Posledné zmeny
+---------------
+
+.. git_changelog::