From 27a92bf0794f16bd6abd53429801b4da517ae9ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alejandro=20S=C3=A1nchez=20Yal=C3=AD?= Date: Tue, 28 Nov 2023 23:30:15 -0500 Subject: [PATCH] update sphinx --- docs/conf.py | 137 +++++++++++++++++++++++++++++++++++++++ docs/getting-started.rst | 96 +++++++++++++++++++++++++++ docs/index.rst | 14 +++- logo/heading.svg | 5 +- logo/logo.drawio | 121 +++++----------------------------- 5 files changed, 264 insertions(+), 109 deletions(-) create mode 100644 docs/getting-started.rst diff --git a/docs/conf.py b/docs/conf.py index 9a922ab..1c16dc5 100644 --- a/docs/conf.py +++ b/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 + }, +] diff --git a/docs/getting-started.rst b/docs/getting-started.rst new file mode 100644 index 0000000..3609af0 --- /dev/null +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index 5271782..7f593d9 100644 --- a/docs/index.rst +++ b/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 diff --git a/logo/heading.svg b/logo/heading.svg index 0728641..7a6b89a 100644 --- a/logo/heading.svg +++ b/logo/heading.svg @@ -1 +1,4 @@ -

 mod  

`\mathbb{Z}` mod `n` 
Efficient Modulo Arithmetic with NumPy
Efficient Modulo Arithmetic with NumPyText is not SVG - cannot display + + + +
Efficient Modulo Arithmetic with NumPy
Efficient Modulo Arithmetic with Num...

 mod 

`\mathbb{Z}` mod `n`Text is not SVG - cannot display diff --git a/logo/logo.drawio b/logo/logo.drawio index 4ab05ad..02998ce 100644 --- a/logo/logo.drawio +++ b/logo/logo.drawio @@ -1,105 +1,16 @@ - - - - - - - - - -
-
-
-

- - - - - - - - - - - - - - - - - - - - - - - - - - mod - - - - - - - - - - - - - - - - - - - - - - - -

-
-
-
- - - `\mathbb{Z}` mod `n` - - - - - - - -
-
-
- - - Efficient Modulo Arithmetic with NumPy - - -
-
-
- - - Efficient Modulo Arithmetic with NumPy - - - - - - - - - Text is not SVG - cannot display - - - - + + + + + + + + + + + + + + + +