Add documentation and gh-pages

.github/workflows/deploy-docs.yml

@@ -0,0 +1,35 @@
+name: Build & Publish Docs with Sphinx
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: |
+          run: python -m pip install .[docs] --upgrade pip
+      - name: Generate API docs & Build sphinx documentation
+        run: |
+          cd docs
+          make clean
+          make html
+          cd ..
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages # The branch the action should deploy to.
+          folder: docs/_build/html # The folder the action should deploy.
+          ssk-key: ${{ secrets.DEPLOY_KEY }}

CODE_OF_CONDUCT.rst

@@ -0,0 +1,113 @@
+Contributor Covenant Code of Conduct
+====================================
+
+Our Pledge
+----------
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for
+everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity
+and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion,
+or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+Our Standards
+-------------
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+Enforcement Responsibilities
+----------------------------
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take
+appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits,
+issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for
+moderation decisions when appropriate.
+
+Scope
+-----
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing
+the community in public spaces. Examples of representing our community include using an official e-mail address, posting
+via an official social media account, or acting as an appointed representative at an online or offline event.
+
+Enforcement
+-----------
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible
+for enforcement at `zhengp@uw.edu <zhengp@uw.edu>`_.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+Enforcement Guidelines
+----------------------
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem
+in violation of this Code of Conduct:
+
+1. Correction
+~~~~~~~~~~~~~
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the
+community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation
+and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+2. Warning
+~~~~~~~~~~
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including
+unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding
+interactions in community spaces as well as external channels like social media. Violating these terms may lead to a
+temporary or permanent ban.
+
+3. Temporary Ban
+~~~~~~~~~~~~~~~~
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified
+period of time. No public or private interaction with the people involved, including unsolicited interaction with those
+enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+4. Permanent Ban
+~~~~~~~~~~~~~~~~
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate
+behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+Attribution
+-----------
+
+This Code of Conduct is adapted from the `Contributor Covenant <https://www.contributor-covenant.org>`_,
+version 2.0, available at `<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>`_.
+
+Community Impact Guidelines were inspired by
+`Mozilla's code of conduct enforcement ladder <https://github.com/mozilla/diversity>`_.
+
+For answers to common questions about this code of conduct, see the FAQ at
+`<https://www.contributor-covenant.org/faq>`_. Translations are available
+at `<https://www.contributor-covenant.org/translations>`_.

README.rst

@@ -1,10 +1,124 @@
-.. image:: https://github.com/zhengp0/xspline/workflows/python-build/badge.svg
+.. image:: https://img.shields.io/pypi/l/xspline
+    :target: https://github.com/zhengp0/xspline/LICENSE
+
+.. image:: https://img.shields.io/pypi/v/xspline
+    :target: https://pypi.org/project/xspline
+
+.. image:: https://img.shields.io/github/actions/workflow/status/zhengp0/xspline/python-build.yml?branch=main
     :target: https://github.com/zhengp0/xspline/actions
 
-.. image:: https://badge.fury.io/py/xspline.svg
-    :target: https://badge.fury.io/py/xspline
+.. image:: https://img.shields.io/badge/docs-here-green
+    :target: https://zhengp0.github.io/xspline
+
 
 XSpline
 =======
 
 Advanced spline package that provides b-spline bases, their derivatives and integrals.
+
+
+Installation
+------------
+
+XSpline requires python 3.10 or higher. XSpline only depends on ``numpy>=1.25.1``.
+It can be installed via
+
+.. code:: bash
+
+    pip install xspline>=0.1.0
+
+For developers, you can clone the repository and install the package in the
+development mode.
+
+.. code::
+
+    git clone https://github.com/zhengp0/xspline.git
+    cd xspline
+    pip install -e ".[test,docs]"
+
+
+Usage
+-----
+
+You can use XSpline as a univariate function or use it to get design matrix.
+
+.. code:: python
+
+    import numpy as np
+    import matplotlib.pyplot as plt
+    from xspline import XSpline
+
+    spline = XSpline(knots=[0, 0.25, 0.5, 0.75, 1], degree=3)
+    x = np.arange(0, 1.01, 0.01)
+
+
+One is to use XSpline as a univariate function. In this case, user must provide
+coefficients for the spline bases.
+
+.. code:: python
+
+    np.random.seed(123)
+    spline.coef = np.random.randn(len(spline))
+    y, design_mat = spline(x), spline.get_design_mat(x)
+
+    fig, ax = plt.subplots(1, 2, figsize=(10, 3))
+    ax[0].plot(x, y)
+    ax[1].plot(x, design_mat)
+
+.. image:: docs/images/readme_usage_0.png
+
+XSpline can be used to obtain derivatives.
+
+.. code:: python
+
+    dy, ddesign_mat = spline(x, order=1), spline.get_design_mat(x, order=1)
+
+    fig, ax = plt.subplots(1, 2, figsize=(10, 3))
+    ax[0].plot(x, dy)
+    ax[1].plot(x, ddesign_mat)
+
+.. image:: docs/images/readme_usage_1.png
+
+XSpline can be used to obtain definite integrals.
+
+.. code:: python
+
+    iy, idesign_mat = spline(x, order=-1), spline.get_design_mat(x, order=-1)
+
+    fig, ax = plt.subplots(1, 2, figsize=(10, 3))
+    ax[0].plot(x, iy)
+    ax[1].plot(x, idesign_mat)
+
+.. image:: docs/images/readme_usage_2.png
+
+XSpline can extrapolate with different polynomial options
+
+.. code:: python
+
+    np.random.seed(123)
+    # constant extrapolation one the left and linear extrapolation on the right
+    spline = XSpline(
+        knots=[0, 0.25, 0.5, 0.75, 1],
+        degree=3,
+        ldegree=0,
+        rdegree=1,
+        coef=np.random.randn(len(spline)),
+    )
+    x = np.arange(-0.5, 1.51, 0.01)
+    y, design_mat = spline(x), spline.get_design_mat(x)
+
+    fig, ax = plt.subplots(1, 2, figsize=(10, 3))
+    ax[0].plot(x, y)
+    ax[1].plot(x, design_mat)
+    for i in range(len(ax)):
+        ax[i].vlines(
+            [0, 1],
+            ymin=0,
+            ymax=1,
+            transform=ax[i].get_xaxis_transform(),
+            linestyle="--",
+            linewidth=1,
+            color="grey",
+        )
+
+.. image:: docs/images/readme_usage_3.png

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/_static/css/custom.css

@@ -0,0 +1,20 @@
+/* reduce the size of the main text */
+
+p {
+  font-size: 0.95rem;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-weight: 500;
+}
+
+.sidebar-brand-text {
+  font-size: 1rem;
+  font-weight: 500;
+  margin: auto;
+}

docs/api_reference/index.rst

@@ -0,0 +1,8 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   *

docs/api_reference/xspline.bspl.rst

@@ -0,0 +1,7 @@
+xspline.bspl
+============
+
+.. automodule:: xspline.bspl
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api_reference/xspline.indi.rst

@@ -0,0 +1,7 @@
+xspline.indi
+=============
+
+.. automodule:: xspline.indi
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api_reference/xspline.poly.rst

@@ -0,0 +1,7 @@
+xspline.poly
+=============
+
+.. automodule:: xspline.poly
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api_reference/xspline.xfunction.rst

@@ -0,0 +1,7 @@
+xspline.xfunction
+=================
+
+.. automodule:: xspline.xfunction
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api_reference/xspline.xspl.rst

@@ -0,0 +1,7 @@
+xspline.xspl
+=============
+
+.. automodule:: xspline.xspl
+   :members:
+   :undoc-members:
+   :show-inheritance: