diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..e69de29 diff --git a/README.md b/README.md index d0838ff..d53e4a5 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@
- Logo + Logo diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..c291b47 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +api/ +build/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/extra.css b/docs/_static/extra.css new file mode 100644 index 0000000..8ab1bd9 --- /dev/null +++ b/docs/_static/extra.css @@ -0,0 +1,50 @@ +/* Set the colors for the light theme */ +[data-md-color-scheme="default"] { + --md-primary-fg-color: #344FA1; + --md-accent-fg-color: #4564C3; +} + +/* Set the colors for the dark theme */ +[data-md-color-scheme="slate"] { + --md-primary-fg-color: #EAA915; + --md-accent-fg-color: #EEBA44; +} +[data-md-color-scheme="slate"] .md-header { + background-color: #344FA1; +} +[data-md-color-scheme="slate"] .md-tabs { + background-color: #344FA1; +} + +/* @media screen and (max-width: 76.1875em) */ +.md-nav--primary .md-nav__title[for=__drawer] { + background-color: #344FA1; +} +.md-source { + background-color: #344FA1; +} + +/* Fix line numbers in code blocks */ +.linenos { + background-color: var(--md-default-bg-color--light); + margin-right: 0.5rem; +} + +/* Override md-tab-set colors. */ +.md-typeset .tabbed-labels { + --md-accent-fg-color: var(--md-primary-fg-color); +} + +/* Modify Sphinx Immaterial python-apigen linkable parameter coloring. */ +.sig-param a.reference span .pre { + color: var(--md-code-hl-generic-color); +} +.sig-param a.reference span .pre:hover { + color: var(--md-accent-fg-color); +} + +/* Override announcement banner colors */ +.md-banner { + background-color: var(--md-typeset-mark-color); + color: var(--md-default-fg-color); +} diff --git a/docs/_templates/base.html b/docs/_templates/base.html new file mode 100644 index 0000000..eb68974 --- /dev/null +++ b/docs/_templates/base.html @@ -0,0 +1,17 @@ +{% extends "!base.html" %} + +{% block announce %} +

+ Enjoying the library? Give us a + + on + GitHub. +

+{% endblock %} + +{% block outdated %} +You're not viewing the latest version. + + Click here to go to latest. + +{% endblock %} diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..9a922ab --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,148 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.abspath(".")) +sys.path.insert(0, os.path.abspath("..")) + + +# -- Project information ----------------------------------------------------- + +project = "Zmodn" +copyright = "2023, Alejandro Sánchez Yalí" +author = "Alejandro Sánchez Yalí" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx.ext.mathjax", + "sphinx.ext.intersphinx", + "sphinx_last_updated_by_git", + "sphinx_immaterial", + "sphinx_immaterial.apidoc.python.apigen", + "sphinx_math_dollar", + "myst_parser", + "sphinx_design", + "IPython.sphinxext.ipython_console_highlighting", + "IPython.sphinxext.ipython_directive", + "ipython_with_reprs", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# 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. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_immaterial" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + + +html_css_files = [ + "extra.css", +] + +# Define a custom inline Python syntax highlighting literal +rst_prolog = """ +.. role:: python(code) + :language: python + :class: highlight +""" +# Sets the default role of `content` to :python:`content`, which uses the custom Python syntax highlighting inline literal +default_role = "python" + +html_title = "Zmodn" +html_favicon = "../logo/favicon.png" +html_logo = "../logo/favicon.png" + +# Sphinx Immaterial theme options +html_theme_options = { + "icon": { + "repo": "fontawesome/brands/github", + }, + "repo_url": "https://github.com/asanchezyali/Zmodn", + "repo_name": "asanchezyali/Zmodn", + "social": [ + { + "icon": "fontawesome/brands/github", + "link": "https://github.com/asanchezyali/Zmodn", + }, + { + "icon": "fontawesome/brands/twitter", + "link": "https://twitter.com/asanchezyali", + }, + ], + "edit_uri": "", + "globaltoc_collapse": False, + "features": [ + # "navigation.expand", + "navigation.tabs", + # "toc.integrate", + # "navigation.sections", + # "navigation.instant", + # "header.autohide", + "navigation.top", + "navigation.tracking", + "toc.follow", + "toc.sticky", + "content.tabs.link", + "announce.dismiss", + ], + "palette": [ + { + "media": "(prefers-color-scheme: light)", + "scheme": "default", + "toggle": { + "icon": "material/weather-night", + "name": "Switch to dark mode", + }, + }, + { + "media": "(prefers-color-scheme: dark)", + "scheme": "slate", + "toggle": { + "icon": "material/weather-sunny", + "name": "Switch to light mode", + }, + }, + ], + "analytics": { + "provider": "google", + "property": "G-4FW9NCNFZH", + }, + "version_dropdown": True, + "version_json": "../versions.json", +} + +html_last_updated_fmt = "" +html_use_index = True +html_domain_indices = True diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..9b8f97b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. Zmodn documentation master file, created by + sphinx-quickstart on Thu Nov 23 16:31:16 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Zmodn's documentation! +================================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/ipython_with_reprs.py b/docs/ipython_with_reprs.py new file mode 100644 index 0000000..10f9b47 --- /dev/null +++ b/docs/ipython_with_reprs.py @@ -0,0 +1,96 @@ +""" +Sphinx extension that adds `ipython-with-element_reprs` directive. +""" +from typing import List + +import docutils.nodes +import sphinx.addnodes +import sphinx.application +import sphinx.util.docutils +import sphinx.util.logging + +logger = sphinx.util.logging.getLogger(__name__) + +ELEMENT_REPR_TO_TITLE = { + "int": "Integer", + "poly": "Polynomial", + "power": "Power", +} + + +class IPythonWithReprsDirective(sphinx.util.docutils.SphinxDirective): + has_content = True + required_arguments = 1 + optional_arguments = 1 + option_spec = { + "name": str, + } + + def run(self) -> List[docutils.nodes.Node]: + self.assert_has_content() + + # Parse input parameters + element_reprs = self.arguments[0].split(",") + titles = [ELEMENT_REPR_TO_TITLE[element_repr] for element_repr in element_reprs] + field = self.options.get("name", "GF") + + ws = " " + new_lines = [ + ".. md-tab-set::", + "", + ] + + for element_repr, title in zip(element_reprs, titles): + new_lines += [ + f"{ws}.. md-tab-item:: {title}", + "", + f"{ws}{ws}.. ipython:: python", + "", + ] + + # Set the Galois field element representation + first_code_line = self.content[0] + if first_code_line.startswith(f"{field} = "): + assert "repr=" not in first_code_line + if element_repr == "int": + new_first_code_line = first_code_line + else: + items = first_code_line.rsplit(")", 1) + assert len(items) == 2 + items.insert(1, f', repr="{element_repr}")') + new_first_code_line = "".join(items) + new_lines += [ + f"{ws}{ws}{ws}{new_first_code_line}", + ] + else: + new_lines += [ + f"{ws}{ws}{ws}@suppress", + f'{ws}{ws}{ws}{field}.repr("{element_repr}")', + f"{ws}{ws}{ws}{first_code_line}", + ] + + # Add the raw python code + for code_line in self.content[1:]: + new_lines += [ + f"{ws}{ws}{ws}{code_line}", + ] + + # Reset the element representation + new_lines += [ + f"{ws}{ws}{ws}@suppress", + f"{ws}{ws}{ws}{field}.repr()", + "", + ] + + self.state_machine.insert_input(new_lines, self.state_machine.input_lines.source(0)) + + return [] + + +def setup(app: sphinx.application.Sphinx): + app.add_directive("ipython-with-reprs", IPythonWithReprsDirective) + + return { + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/logo/.DS_Store b/logo/.DS_Store new file mode 100644 index 0000000..5008ddf Binary files /dev/null and b/logo/.DS_Store differ diff --git a/logo/favicon.drawio b/logo/favicon.drawio new file mode 100644 index 0000000..fe52c9a --- /dev/null +++ b/logo/favicon.drawio @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/logo/favicon.png b/logo/favicon.png new file mode 100644 index 0000000..58f5884 Binary files /dev/null and b/logo/favicon.png differ diff --git a/logo/logo-title.drawio b/logo/logo-title.drawio new file mode 100644 index 0000000..9843a79 --- /dev/null +++ b/logo/logo-title.drawio @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/logo/logo.drawio b/logo/logo.drawio index 2484035..4ab05ad 100644 --- a/logo/logo.drawio +++ b/logo/logo.drawio @@ -1,16 +1,105 @@ - - - - - - - - - - - - - - - - + + + + + + + + + +
+
+
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + mod + + + + + + + + + + + + + + + + + + + + + + + +

+
+
+
+ + + `\mathbb{Z}` mod `n` + + + + + + + +
+
+
+ + + Efficient Modulo Arithmetic with NumPy + + +
+
+
+ + + Efficient Modulo Arithmetic with NumPy + + + + + + + + + Text is not SVG - cannot display + + + + diff --git a/logo/logo.drawio.svg b/logo/logo.drawio.svg deleted file mode 100644 index 4ab05ad..0000000 --- a/logo/logo.drawio.svg +++ /dev/null @@ -1,105 +0,0 @@ - - - - - - - - - -
-
-
-

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

-
-
-
- - - `\mathbb{Z}` mod `n` - - - - - - - -
-
-
- - - Efficient Modulo Arithmetic with NumPy - - -
-
-
- - - Efficient Modulo Arithmetic with NumPy - - - - - - - - - Text is not SVG - cannot display - - - - diff --git a/logo/logo.png b/logo/logo.png new file mode 100644 index 0000000..92de159 Binary files /dev/null and b/logo/logo.png differ diff --git a/logo/logo.svg b/logo/logo.svg new file mode 100644 index 0000000..0728641 --- /dev/null +++ b/logo/logo.svg @@ -0,0 +1 @@ +

 mod  

`\mathbb{Z}` mod `n` 
Efficient Modulo Arithmetic with NumPy
Efficient Modulo Arithmetic with NumPyText is not SVG - cannot display diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..73569cb --- /dev/null +++ b/requirements.txt @@ -0,0 +1,16 @@ +cfgv==3.4.0 ; python_version >= "3.11" and python_version < "4.0" +colorama==0.4.6 ; python_version >= "3.11" and python_version < "4.0" and sys_platform == "win32" +distlib==0.3.7 ; python_version >= "3.11" and python_version < "4.0" +filelock==3.12.4 ; python_version >= "3.11" and python_version < "4.0" +identify==2.5.30 ; python_version >= "3.11" and python_version < "4.0" +iniconfig==2.0.0 ; python_version >= "3.11" and python_version < "4.0" +nodeenv==1.8.0 ; python_version >= "3.11" and python_version < "4.0" +numpy==1.26.1 ; python_version >= "3.11" and python_version < "3.13" +packaging==23.2 ; python_version >= "3.11" and python_version < "4.0" +platformdirs==3.11.0 ; python_version >= "3.11" and python_version < "4.0" +pluggy==1.3.0 ; python_version >= "3.11" and python_version < "4.0" +pre-commit==3.5.0 ; python_version >= "3.11" and python_version < "4.0" +pytest==7.4.3 ; python_version >= "3.11" and python_version < "4.0" +pyyaml==6.0.1 ; python_version >= "3.11" and python_version < "4.0" +setuptools==68.2.2 ; python_version >= "3.11" and python_version < "4.0" +virtualenv==20.24.5 ; python_version >= "3.11" and python_version < "4.0" diff --git a/zmodn/__init__.py b/zmodn/__init__.py index aece4a3..33c3e90 100644 --- a/zmodn/__init__.py +++ b/zmodn/__init__.py @@ -1,4 +1,4 @@ from .zmodn import Zmodn import sys -sys.modules["Zmodn"] = Zmodn \ No newline at end of file +sys.modules["Zmodn"] = Zmodn