Merge branch 'master' into feature/perf_test

.readthedocs.yaml

@@ -0,0 +1,27 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for detail
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+
+# Build all formats
+formats:
+  - pdf
+  - epub
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt
+   - method: pip
+     path: .

README.md

@@ -1,4 +1,5 @@
 # mmh3
+[![Documentation Status](https://readthedocs.org/projects/mmh3/badge/?version=latest)](https://mmh3.readthedocs.io/en/latest/?badge=latest)
 [![GitHub Super-Linter](https://github.com/hajimes/mmh3/workflows/Super-Linter/badge.svg?branch=master)](https://github.com/hajimes/mmh3/actions?query=workflow%3ASuper-Linter+branch%3Amaster)
 [![Build](https://github.com/hajimes/mmh3/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/hajimes/mmh3/actions/workflows/build.yml?branch=master)
 [![PyPi Version](https://img.shields.io/pypi/v/mmh3.svg?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/mmh3/)
@@ -13,6 +14,8 @@ Combined with probabilistic techniques like a [Bloom filter](https://en.wikipedi
 
 Another common use of mmh3 is to [calculate favicon hashes](https://gist.github.com/yehgdotnet/b9dfc618108d2f05845c4d8e28c5fc6a) used by [Shodan](https://www.shodan.io), the world's first IoT search engine.
 
+This page offers a quick start guide. For more detailed information, see the [documentation](https://mmh3.readthedocs.io/en/latest/).
+
 ## How to use
 ### Install
 ```shell
@@ -117,10 +120,10 @@ b'\x82_n\xdd \xac\xb6j\xef\x99\xb1e\xc4\n\xc9\xfd'
   * A hash function now returns the same value under big-endian platforms as that under little-endian ones (<https://github.com/hajimes/mmh3/issues/47>).
   * Remove the `__version__` constant from the module (<https://github.com/hajimes/mmh3/issues/42>). Use `importlib.metadata` instead.
 
-See [CHANGELOG.md](./docs/CHANGELOG.md) for the complete changelog.
+See [Changelog](https://mmh3.readthedocs.io/en/latest/changelog.html) for the complete changelog.
 
 ## License
-[MIT](./LICENSE), unless otherwise noted within a file.
+[MIT](https://github.com/hajimes/mmh3/blob/master/LICENSE), unless otherwise noted within a file.
 
 ## Known Issues
 ### Getting different results from other MurmurHash3-based libraries
@@ -153,7 +156,7 @@ Be careful so that these seeds do not exceed 32-bit. Unexpected results may happ
 ```
 
 ## Contributing Guidelines
-See [CONTRIBUTING.md](./docs/CONTRIBUTING.md).
+See [Contributing](https://mmh3.readthedocs.io/en/latest/CONTRIBUTING.html).
 
 ## Authors
 MurmurHash3 was originally developed by Austin Appleby and distributed under public domain [https://github.com/aappleby/smhasher](https://github.com/aappleby/smhasher).

docs/CODE_OF_CONDUCT.md

@@ -1,3 +1,3 @@
 # Code of Conduct
 
-This project has adopted the ACM Code of Ethics and Professional Conduct ([https://www.acm.org/code-of-ethics](https://www.acm.org/code-of-ethics)) in the version adopted in June 22nd, 2018.
+This project adheres the ACM Code of Ethics and Professional Conduct ([https://www.acm.org/code-of-ethics](https://www.acm.org/code-of-ethics)), as specified in the version adopted in June 22nd, 2018.

docs/CONTRIBUTING.md

@@ -1,9 +1,9 @@
-# mmh3 Contributing Guidelines
+# Contributing
 
 Thank you for your interest in contributing to the `mmh3` project!
 
-Read [README.md](../README.md) to get an overview of the `mmh3` project,
-and follow our [Code of Conduct](./CODE_OF_CONDUCT.md)
+Read [README](https://github.com/hajimes/mmh3/blob/master/README.md) to get an overview of the `mmh3` project,
+and follow our [Code of Conduct](./CODE_OF_CONDUCT)
 (ACM Code of Ethics and Professional Conduct).
 
 ## Issues
@@ -22,7 +22,7 @@ As of 4.1.0, the layout of the project is as follows:
 
 - `src/mmh3`
   - `mmh3module.c`: the main file that serves as the interface between Python and the MurmurHash3 c implementations.
-  - `murmurhash.c`: implementations of the MurmurHash3 family. Auto-generated from Austin Appleby's original code. DO NOT edit this file manually. See [README in the util directory](../util/README.md) for details.
+  - `murmurhash.c`: implementations of the MurmurHash3 family. Auto-generated from Austin Appleby's original code. DO NOT edit this file manually. See [README in the util directory](https://github.com/hajimes/mmh3/blob/master/util/README.md) for details.
   - `murmurhash.h`: headers and macros for MurmurHash3. Auto-generated from `util/refresh.py`. DO NOT edit this file manually.
   - `hashlib.h`: taken from [CPython's code base](https://github.com/python/cpython/blob/9ce0f48e918860ffa32751a85b0fe7967723e2e3/Modules/hashlib.h).
 - `util`

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)

docs/api.rst

@@ -0,0 +1,7 @@
+API Reference
+================
+
+.. automodule:: mmh3
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/CHANGELOG.md → docs/changelog.md

@@ -1,15 +1,19 @@
 # Changelog
+
 ## 4.1.0 (2024-01-09)
+
 * Add support for Python 3.12.
 * Change the project structure to fix issues when using Bazel (<https://github.com/hajimes/mmh3/issues/50>).
 * Fix incorrect type hints (<https://github.com/hajimes/mmh3/issues/51>).
 * Fix invalid results on s390x when the arg `x64arch` of `hash64` or `hash_bytes` is set to `False` (<https://github.com/hajimes/mmh3/issues/52>).
 
 ## 4.0.1 (2023-07-14)
+
 * Fix incorrect type hints.
 * Refactor the project structure (<https://github.com/hajimes/mmh3/issues/48>).
 
 ## 4.0.0 (2023-05-22)
+
 * Add experimental support for `hashlib`-compliant hasher classes (<https://github.com/hajimes/mmh3/issues/39>). Note that they are not yet fully tuned for performance.
 * Add support for type hints (<https://github.com/hajimes/mmh3/issues/44>).
 * Add wheels for more platforms (`musllinux`, `s390x`, `win_arm64`, and `macosx_universal2`).
@@ -21,13 +25,15 @@
   * Remove the `__version__` constant from the module (<https://github.com/hajimes/mmh3/issues/42>). Use `importlib.metadata` instead.
 
 ## 3.1.0 (2023-03-24)
+
 * Add support for Python 3.10 and 3.11. Thanks [wouter bolsterlee](https://github.com/wbolster) and [Dušan Nikolić](https://github.com/n-dusan)!
 * Drop support for Python 3.6; remove legacy code for Python 2.x at the source code level.
 * Add support for 32-bit architectures such as `i686` and `armv7l`. From now on, `hash` and `hash_from_buffer` on these architectures will generate the same hash values as those on other environments. Thanks [Danil Shein](https://github.com/dshein-alt)!
 * In relation to the above, `manylinux2014_i686` wheels are now available.
 * Support for hashing huge data (>16GB). Thanks [arieleizenberg](https://github.com/arieleizenberg)!
 
 ## 3.0.0 (2021-02-23)
+
 * Python wheels are now available, thanks to the power of [cibuildwheel](https://github.com/joerick/cibuildwheel).
   * Supported platforms are `manylinux1_x86_64`, `manylinux2010_x86_64`, `manylinux2014_aarch64`, `win32`, `win_amd64`, `macosx_10_9_x86_64`, and `macosx_11_0_arm64` (Apple Silicon).
 * Add support for newer macOS environments. Thanks [Matthew Honnibal](https://github.com/honnibal)!
@@ -36,35 +42,43 @@
 * Migrate CI from Travis CI and AppVeyor to GitHub Actions.
 
 ## 2.5.1 (2017-10-31)
+
 * Bugfix for `hash_bytes`. Thanks [doozr](https://github.com/doozr)!
 
 ## 2.5 (2017-10-28)
+
 * Add `hash_from_buffer`. Thanks [Dimitri Vorona](https://github.com/alendit)!
 * Add a keyword argument `signed`.
 
 ## 2.4 (2017-05-27)
+
 * Support seeds with 32-bit unsigned integers; thanks [Alexander Maznev](https://github.com/pik)!
 * Support 64-bit data (under 64-bit environments)
 * Fix compile errors for Python 3.6 under Windows systems.
 * Add unit testing and continuous integration with Travis CI and AppVeyor.
 
 ## 2.3.2 (2017-05-26)
-* Relicensed from public domain to [CC0-1.0](./LICENSE).
+
+* Relicensed from public domain to CC0-1.0.
 
 ## 2.3.1 (2015-06-07)
+
 * Fix compile errors for gcc >=5.
 
 ## 2.3 (2013-12-08)
+
 * Add `hash128`, which returns a 128-bit signed integer.
 * Fix a misplaced operator which could cause memory leak in a rare condition.
 * Fix a malformed value to a Python/C API function which may cause runtime errors in recent Python 3.x versions.
 
 The first two commits are from [Derek Wilson](https://github.com/underrun). Thanks!
 
 ## 2.2 (2013-03-03)
+
 * Improve portability to support systems with old gcc (version < 4.4) such as CentOS/RHEL 5.x. (Commit from [Micha Gorelick](https://github.com/mynameisfiber). Thanks!)
 
 ## 2.1 (2013-02-25)
+
 * Add `__version__` constant. Check if it exists when the following revision matters for your application.
 * Incorporate the revision r147, which includes robustness improvement and minor tweaks.
 
@@ -80,8 +94,10 @@ Beware that due to this revision, **the result of 32-bit version of 2.1 is NOT t
 The results of hash64 and hash_bytes remain unchanged. Austin Appleby, the author of Murmurhash, ensured this revision was the final modification to MurmurHash3's results and any future changes would be to improve performance only.
 
 ## 2.0 (2011-06-07)
+
 * Support both Python 2.7 and 3.x.
 * Change the module interface.
 
 ## 1.0 (<= 2011-04-27)
+
 * As [Softpedia collected mmh3 1.0 on April 27, 2011](https://web.archive.org/web/20110430172027/https://linux.softpedia.com/get/Programming/Libraries/mmh3-68314.shtml), it must have been uploaded to PyPI on or slightly before this date.

docs/conf.py

@@ -0,0 +1,31 @@
+# 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 sys
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "mmh3"
+copyright = "2011-2024, Hajime Senuma"
+author = "Hajime Senuma"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx.ext.autodoc", "myst_parser"]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "shibuya"
+html_static_path = ["_static"]
+html_theme_options = {
+    "github_url": "https://github.com/hajimes/mmh3",
+}

docs/index.rst

@@ -0,0 +1,25 @@
+mmh3 documentation
+==================
+mmh3 is a Python extension for `MurmurHash (MurmurHash3) <https://en.wikipedia.org/wiki/MurmurHash>`_, a set of fast and robust non-cryptographic hash functions invented by Austin Appleby.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guideline
+
+   Quickstart<readme_link>
+   api
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Project documentation
+
+   CONTRIBUTING
+   changelog
+   CODE_OF_CONDUCT
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

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

docs/readme_link.md

@@ -0,0 +1,3 @@
+<!-- markdownlint-disable -->
+```{include} ../README.md
+```

docs/requirements.in

@@ -0,0 +1,3 @@
+myst-parser
+shibuya
+sphinx

docs/requirements.txt

@@ -0,0 +1,69 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile requirements.in
+#
+alabaster==0.7.16
+    # via sphinx
+babel==2.15.0
+    # via sphinx
+certifi==2024.7.4
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+docutils==0.21.2
+    # via
+    #   myst-parser
+    #   sphinx
+idna==3.7
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.4
+    # via
+    #   myst-parser
+    #   sphinx
+markdown-it-py==3.0.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+markupsafe==2.1.5
+    # via jinja2
+mdit-py-plugins==0.4.1
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+myst-parser==3.0.1
+    # via -r requirements.in
+packaging==24.1
+    # via sphinx
+pygments==2.18.0
+    # via sphinx
+pyyaml==6.0.1
+    # via myst-parser
+requests==2.32.3
+    # via sphinx
+shibuya==2024.7.13
+    # via -r requirements.in
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==7.4.5
+    # via
+    #   -r requirements.in
+    #   myst-parser
+    #   shibuya
+sphinxcontrib-applehelp==1.0.8
+    # via sphinx
+sphinxcontrib-devhelp==1.0.6
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.5
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.7
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.10
+    # via sphinx
+urllib3==2.2.2
+    # via requests

pyproject.toml

@@ -35,7 +35,7 @@ test = [
 [project.urls]
 Homepage = "https://pypi.org/project/mmh3/"
 Repository = "https://github.com/hajimes/mmh3"
-Changelog = "https://github.com/hajimes/mmh3/blob/master/docs/CHANGELOG.md"
+Changelog = "https://github.com/hajimes/mmh3/blob/master/docs/changelog.md"
 "Bug Tracker" = "https://github.com/hajimes/mmh3/issues"
 
 [tool.isort]