update sphinx

docs/conf.py

@@ -48,6 +48,22 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+source_suffix = [".rst", ".md", ".ipynb"]
+
+# Tell sphinx that ReadTheDocs will create an index.rst file as the main file,
+# not the default of contents.rst.
+master_doc = "index"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
@@ -146,3 +162,124 @@
 html_last_updated_fmt = ""
 html_use_index = True
 html_domain_indices = True
+
+
+# -- Extension configuration -------------------------------------------------
+
+# Create hyperlinks to other documentation
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+
+autodoc_default_options = {
+    "imported-members": True,
+    "members": True,
+    # "special-members": True,
+    # "inherited-members": "ndarray",
+    # "member-order": "groupwise",
+}
+autodoc_typehints = "signature"
+autodoc_typehints_description_target = "documented"
+autodoc_typehints_format = "short"
+
+autodoc_type_aliases = {
+    "ElementLike": "~typing.ElementLike",
+    "IterableLike": "~typing.IterableLike",
+    "ArrayLike": "~typing.ArrayLike",
+    "ShapeLike": "~typing.ShapeLike",
+    "DTypeLike": "~typing.DTypeLike",
+    "PolyLike": "~typing.PolyLike",
+}
+
+ipython_execlines = ["import math", "import numpy as np", "import zmodn"]
+
+myst_enable_extensions = ["dollarmath"]
+
+mathjax_config = {
+    "tex2jax": {
+        "inlineMath": [["\\(", "\\)"]],
+        "displayMath": [["\\[", "\\]"]],
+    },
+}
+mathjax3_config = {
+    "tex": {
+        "inlineMath": [["\\(", "\\)"]],
+        "displayMath": [["\\[", "\\]"]],
+    }
+}
+
+
+# -- Sphinx Immaterial configs -------------------------------------------------
+
+
+# Python apigen configuration
+python_apigen_modules = {
+    "zmodn": "api/zmodn.",
+}
+
+python_apigen_default_groups = [
+    ("class:.*", "Classes"),
+    ("data:.*", "Variables"),
+    ("function:.*", "Functions"),
+    ("classmethod:.*", "Class methods"),
+    ("method:.*", "Methods"),
+    (r"method:.*\.[A-Z][A-Za-z,_]*", "Constructors"),
+    (r"method:.*\.__[A-Za-z,_]*__", "Special methods"),
+    (r"method:.*\.__(init|new)__", "Constructors"),
+    (r"method:.*\.__(str|repr)__", "String representation"),
+    ("property:.*", "Properties"),
+    (r".*:.*\.is_[a-z,_]*", "Attributes"),
+]
+python_apigen_default_order = [
+    ("class:.*", 10),
+    ("data:.*", 11),
+    ("function:.*", 12),
+    ("classmethod:.*", 40),
+    ("method:.*", 50),
+    (r"method:.*\.[A-Z][A-Za-z,_]*", 20),
+    (r"method:.*\.__[A-Za-z,_]*__", 28),
+    (r"method:.*\.__(init|new)__", 20),
+    (r"method:.*\.__(str|repr)__", 30),
+    ("property:.*", 60),
+    (r".*:.*\.is_[a-z,_]*", 70),
+]
+python_apigen_order_tiebreaker = "alphabetical"
+python_apigen_case_insensitive_filesystem = False
+python_apigen_show_base_classes = True
+
+# Python domain directive configuration
+python_type_aliases = autodoc_type_aliases
+python_module_names_to_strip_from_xrefs = ["collections.abc"]
+
+# General API configuration
+object_description_options = [
+    ("py:.*", dict(include_rubrics_in_toc=True)),
+]
+
+sphinx_immaterial_custom_admonitions = [
+    {
+        "name": "seealso",
+        "title": "See also",
+        "classes": ["collapsible"],
+        "icon": "fontawesome/regular/eye",
+        "override": True,
+    },
+    {
+        "name": "star",
+        "icon": "octicons/star-16",
+        "color": (255, 233, 3),  # Gold
+    },
+    {
+        "name": "fast-performance",
+        "title": "Faster performance",
+        "icon": "material/speedometer",
+        "color": (47, 177, 112),  # Green: --md-code-hl-string-color
+    },
+    {
+        "name": "slow-performance",
+        "title": "Slower performance",
+        "icon": "material/speedometer-slow",
+        "color": (230, 105, 91),  # Red: --md-code-hl-number-color
+    },
+]

docs/getting-started.rst

@@ -0,0 +1,96 @@
+The :doc:`getting-started` guide is intended to help you get started with installing and using the library in your own
+projects. See ":doc:`Basic Usage`" for more detailed information on how to use the library.
+
+Install the package
+-------------------
+
+The last stable release is available on PyPI and can be installed with pip:
+
+.. code-block:: console
+
+    pip install zmodn
+    zmodn.__version__
+
+Create a :obj:`Zmodn` instance
+------------------------------
+
+The :obj:`Zmodn` class is the main interface to the library. It represents a set of integers modulo a given modulus. The
+modulus must be a positive integer. The representatives of the set are given as a list of integers or a single integer.
+In this example, we create a :obj:`Zmodn` instance representing the set of integers modulo 5 with representatives 1, 2,
+3, 4, and 5 (which are equivalent to 1, 2, 3, 4, and 0 modulo 5, respectively):
+
+.. code-block:: python
+
+    from zmodn import Zmodn
+    zmodn = Zmodn([1, 2, 3, 4, 5], 5)
+
+The :obj:`Zmodn` class is a subclass of :obj:`numpy.ndarray`, so it can be used in the same way as a NumPy array:
+
+.. code-block:: python
+
+    zmodn[0]
+    zmodn[1:3]
+    zmodn[0] = 6
+    zmodn[1:3] = [7, 8]
+    zmodn[0] = 1
+    zmodn[1:3] = [2, 3]
+
+The :obj:`Zmodn` class also supports the :obj:`len` function, which returns the number of representatives:
+
+.. code-block:: python
+
+    len(zmodn)
+
+The :obj:`Zmodn` class supports the :obj:`in` operator, which checks if a given representative is in the set:
+
+.. code-block:: python
+
+    1 in zmodn
+    2 in zmodn
+    3 in zmodn
+    4 in zmodn
+    5 in zmodn
+    6 in zmodn
+    7 in zmodn
+    8 in zmodn
+
+The :obj:`Zmodn` class supports the :obj:`bool` function, which returns :obj:`True` if the set is not empty and
+
+:obj:`False` otherwise:
+
+.. code-block:: python
+
+    bool(zmodn)
+
+Perform arithmetic operations
+-----------------------------
+
+Once you have two :obj:`Zmodn` instances, you can perform arithmetic can be performed using normal NumPy arithmetic.
+
+standard element-wise array arithmetic operations -- addition, subtraction, multiplication, division and exponentiation
+are easily performed on :obj:`Zmodn` instances. For example, to add two :obj:`Zmodn` instances, you can use the :obj:`+`
+operator:
+
+.. code-block:: python
+
+    zmodn1 = Zmodn([1, 2, 3, 4, 5], 5)
+    zmodn2 = Zmodn([1, 2, 3, 4, 5], 5)
+    zmodn1 + zmodn2
+
+The :obj:`Zmodn` class also supports the :obj:`-`, :obj:`*`, :obj:`/`, and :obj:`**` operators:
+
+.. code-block:: python
+
+    zmodn1 - zmodn2
+    zmodn1 * zmodn2
+    zmodn1 / zmodn2
+    zmodn1 ** zmodn2
+
+The :obj:`Zmodn` class supports the :obj:`==` and :obj:`!=` operators, which check if two :obj:`Zmodn` instances are equal or not equal, respectively:
+
+.. code-block:: python
+
+    zmodn1 == zmodn2
+    zmodn1 != zmodn2
+
+See :doc:`/basic-usage/operations` for more information on the arithmetic operations.

docs/index.rst

@@ -27,7 +27,6 @@ Here is a simple example of how to use Zmodn:
 
 .. code-block:: python
 
-   import numpy as np
    from zmodn import Zmodn
 
    # Create a Zmodn object with the representatives 2 and 3 modulo 5
@@ -106,6 +105,15 @@ If this library was useful to you in your research, please cite us. Following th
          Sánchez, A. (2023). Zmodn: Efficient Modulo Arithmetic with NumPy. [Computer software]. https://github.com/asanchezyali/Zmodn
 
 
+
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :caption: Getting Started
+   :hidden:
+
+   getting-started.rst
+
+   .. toctree::
+   :caption: API Reference
+   :hidden:
+
+   api.rst