Add Sphincs-based documentation

.cirrus.yml

@@ -1,4 +1,18 @@
+docs_task:
+  skip: $CIRRUS_BRANCH =~ '.*\.tmp'
+  container:
+    image: python:3.7-slim
+
+  install_script:
+    - apt update && apt install make
+    - pip install --upgrade-strategy eager -U -r docs-requirements.txt
+    - pip install -e .
+
+  script:
+    - make -C docs/ html
+
 lint_task:
+  skip: $CIRRUS_BRANCH =~ '.*\.tmp'
   container:
     image: python:3.7-slim
 
@@ -15,6 +29,7 @@ lint_task:
 
 
 FreeBSD_task:
+  skip: $CIRRUS_BRANCH =~ '.*\.tmp'
   freebsd_instance:
     image: freebsd-12-0-release-amd64
   env:
@@ -37,6 +52,7 @@ FreeBSD_task:
     - ./test.sh
 
 Linux_task:
+  skip: $CIRRUS_BRANCH =~ '.*\.tmp'
   allow_failures: $CIRRUS_TASK_NAME =~ '.*-rc-.*'
   container:
     matrix:
@@ -56,6 +72,7 @@ Linux_task:
     - ./test.sh
 
 macOS_task:
+  skip: $CIRRUS_BRANCH =~ '.*\.tmp'
   osx_instance:
     image: mojave-base
   env:
@@ -81,6 +98,7 @@ macOS_task:
     - ./test.sh
 
 Windows_task:
+  skip: $CIRRUS_BRANCH =~ '.*\.tmp'
   allow_failures: $CIRRUS_TASK_NAME =~ '.*-rc-.*'
   windows_container:
     os_version: 2019

README.md

@@ -1,5 +1,8 @@
 # ppb-vector
-The 2D Vector Class for the PursuedPyBear project.
+The immutable, 2D vector class for the PursuedPyBear project.
+
+`Vector2` implements many convenience features, as well as
+useful mathematical operations for 2D geometry.
 
 ## Install
 
@@ -17,204 +20,7 @@ pip install 'ppb-vector'
     >>> Vector2(3, 4)
     Vector2(3.0, 4.0)
 
-`Vector2` implements many convenience features, as well as
-useful mathematical operations for 2D geometry and linear algebra.
-
-
-## Convenience functions
-
-### Unpacking
-
-    >>> x, y = Vector2(1, 3)
-    >>> print(x)
-    1.0
-    >>> print(y)
-    3.0
-
-### Access Values
-
-Convenient access to `Vector2` members via dot notation, indexes, or keys.
-
-    >>> my_vector = Vector2(2, 3)
-    >>> my_vector.x
-    2.0
-    >>> my_vector[1]
-    3.0
-    >>> my_vector["x"]
-    2.0
-
-Also iterable for translation between Vector2 and other sequence types.
-
-    >>> tuple(Vector2(2, 3))
-    (2.0, 3.0)
-
-
-## Mathematical operators
-
-In addition to `Vector2`, operators also accepts, as second operand,
-vector-like objects such as `tuple`, `list`, and `dict`.
-
-    >>> Vector2(1, 1) + [1, 3]
-    Vector2(2.0, 4.0)
-
-    >>> Vector2(1, 1) + (2, 4)
-    Vector2(3.0, 5.0)
-
-    >>> Vector2(1, 1) + {"x": 3, "y": 5}
-    Vector2(4.0, 6.0)
-
-
-### Addition
-
-    >>> Vector2(1, 0) + (0, 1)
-    Vector2(1.0, 1.0)
-
-### Subtraction
-
-    >>> Vector2(3, 3) - (1, 1)
-    Vector2(2.0, 2.0)
-
-### Equality
-
-Vectors are equal if their coordinates are equal.
-
-    >>> Vector2(1, 0) == (0, 1)
-    False
-
-### Scalar Multiplication
-
-Multiply a `Vector2` by a scalar to get a scaled `Vector2`:
-
-    >>> 3 * Vector2(1, 1)
-    Vector2(3.0, 3.0)
-
-    >>> Vector2(1, 1) * 3
-    Vector2(3.0, 3.0)
-
-    >>> Vector2(1, 1).scale_by(3)
-    Vector2(3.0, 3.0)
-
-
-It is also possible to divide a `Vector2` by a scalar:
-
-    >>> Vector2(3, 3) / 3
-    Vector2(1.0, 1.0)
-
-### Dot Product
-
-Multiply a `Vector2` by another `Vector2` to get the dot product.
-
-    >>> Vector2(1, 1) * (-1, -1)
-    -2.0
-
-### Vector Length
-
-    >>> Vector2(45, 60).length
-    75.0
-
-### Negation
-
-Negating a `Vector2` is equivalent to multiplying it by -1.
-
-    >>> -Vector2(1, 1)
-    Vector2(-1.0, -1.0)
-
-
-## Methods
-
-Useful functions for game development.
-
-### isclose(vector)
-
-Perform an approximate comparison of two vectors.
-
-    >>> Vector2(1, 0).isclose((1, 1e-10))
-    True
-
-`Vector2.isclose` takes optional, keyword arguments, akin to those of
-`math.isclose`:
-- `abs_tol` (absolute tolerance) is the minimum magnitude (of the difference
-  vector) under which two inputs are considered close, without consideration for
-  (the magnitude of) the input values.
-- `rel_tol` (relative tolerance) is the relative error: if the length of the
-  difference vector is less than `rel_tol * input.length` for any `input`,
-  the two vectors are considered close.
-- `rel_to` is an iterable of additional vector-likes whose length (times
-  `rel_tol`) is compared to the length of the difference vector.
-
-By default, `abs_tol = 1e-3`, `rel_tol = 1e-6`, and `rel_to = []`.
-
-### rotate(deg)
-
-Rotate a vector in relation to its own origin and return a new `Vector2`.
-
-    >>> Vector2(1, 0).rotate(90)
-    Vector2(0.0, 1.0)
-
-Positive rotation is counter/anti-clockwise.
-
-### angle(vector)
-
-Compute the angle between two vectors, expressed as a scalar in degrees.
-
-    >>> Vector2(1, 0).angle( (0, 1) )
-    90.0
-
-As with `rotate()`, angles are signed, and refer to a direct coordinate system
-(i.e. positive rotations are counter-clockwise).
-
-`Vector2.angle` is guaranteed to produce an angle between -180° and 180°.
-
-### normalize()
-
-Return a vector with the same direction, and unit length.
-
-    >>> Vector2(3, 4).normalize()
-    Vector2(0.6, 0.8)
-
-### scale(scalar)
-
-Scale given `Vector2` to a given length.
-
-    >>> Vector2(7, 24).scale(2)
-    Vector2(0.56, 1.92)
-
-Note that `Vector2.normalize()` is equivalent to `Vector2.scale(1)`.
-
-    >>> Vector2(7, 24).normalize()
-    Vector2(0.28, 0.96)
-    >>> Vector2(7, 24).scale(1)
-    Vector2(0.28, 0.96)
-
-### truncate(scalar)
-
-Scale a given `Vector2` down to a given length, if it is larger.
-
-    >>> Vector2(7, 24).truncate(3)
-    Vector2(0.84, 2.88)
-
-Note that `Vector2.scale` is equivalent to `Vector2.truncate` when `scalar` is
-less than length.
-
-    >>> Vector2(3, 4).scale(4)
-    Vector2(2.4, 3.2)
-    >>> Vector2(3, 4).truncate(4)
-    Vector2(2.4, 3.2)
-
-    >>> Vector2(3, 4).scale(6)
-    Vector2(3.6, 4.8)
-    >>> Vector2(3, 4).truncate(6)
-    Vector2(3.0, 4.0)
-
-Note: `x.truncate(max_length)` may sometimes be slightly-larger than
-      `max_length`, due to floating-point rounding effects.
-
-### reflect(surface_normal)
-
-Reflect a `Vector2` based on a given surface normal.
 
-    >>> Vector2(5, 3).reflect( (-1, 0) )
-    Vector2(-5.0, 3.0)
+See the [online documentation] for an overview of the functionality.
 
-    >>> Vector2(5, 3).reflect( Vector2(-1, -2).normalize() )
-    Vector2(0.5999999999999996, -5.800000000000001)
+[online documentation]: https://ppb-vector.readthedocs.io/en/latest/

bors.toml

@@ -0,0 +1,12 @@
+status = [
+  "docs",
+  "FreeBSD PYTHON:3.6",
+  "FreeBSD PYTHON:3.7",
+  "lint",
+  "Linux container:python:3.6-slim",
+  "Linux container:python:3.7-slim",
+  "Windows container:python:3.6-windowsservercore-1809",
+  "Windows container:python:3.7-windowsservercore-1809",
+  "macOS PYTHON:3.6.8",
+  "macOS PYTHON:3.7.2",
+]

docs-requirements.txt

@@ -0,0 +1,3 @@
+sphinx
+sphinx-autodoc-annotation
+sphinx_rtd_theme

docs/.gitignore

@@ -0,0 +1 @@
+/_build/

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+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)