chore: add Sphinx docs (#1)

* adding a basic docs page and validating in ci

* adding deploy pages action

.github/workflows/ci.yaml

@@ -24,6 +24,8 @@ jobs:
         run: poetry run pytest
       - name: build
         run: poetry build
+      - name: build docs
+        run: poetry run sphinx-build -b html docs docs/build
   release:
     needs: lint_test_and_build
     permissions:
@@ -40,6 +42,9 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
       - name: Semantic Release
         id: release
         uses: python-semantic-release/python-semantic-release@v8.0.7
@@ -53,3 +58,21 @@ jobs:
         if: steps.release.outputs.released == 'true'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
+      # build and deploy docs to gh-pages
+      # do this as part of the semantic release step to ensure version is bumped
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: 1.4.0
+      - name: Install dependencies
+        run: poetry install --no-interaction
+      - name: Sphinx build
+        run: |
+          poetry run sphinx-build docs _build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true

docs/about.rst

@@ -0,0 +1,34 @@
+About
+=====
+
+Acknowledgements
+----------------
+
+This library is inspired by and uses modified code from the following excellent projects:
+
+* `Locating and Editing Factual Associations in GPT <https://rome.baulab.info/>`_
+* `Linearity of Relation Decoding in Transformer LMs <https://lre.baulab.info/>`_
+
+Contributing
+------------
+
+Any contributions to improve this project are welcome! Please open an issue or pull request in `Github repo <https://github.com/chanind/linear-relational>`_ with bugfixes, changes, and improvements.
+
+License
+-------
+
+Linear-Relational is released under a MIT license.
+
+Citation
+--------
+
+If you use this library in your work, please cite the following:
+
+.. code-block:: bibtex
+
+    @article{chanin2023identifying,
+        title={Identifying Linear Relational Concepts in Large Language Models},
+        author={David Chanin and Anthony Hunter and Oana-Maria Camburu},
+        journal={arXiv preprint arXiv:2311.08968},
+        year={2023}
+    }

docs/conf.py

@@ -0,0 +1,46 @@
+# -- 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
+from datetime import datetime
+
+sys.path.insert(0, os.path.abspath(".."))
+
+from linear_relational import __version__
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "linear-relational"
+copyright = f"{datetime.today().year}, David Chanin"
+author = "David Chanin"
+
+release = __version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.mathjax",
+]
+
+pygments_style = "sphinx"
+
+templates_path = ["_templates"]
+exclude_patterns = [".DS_Store"]
+
+autodoc_typehints = "none"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,60 @@
+Linear-Relational
+=================================================
+
+A library for working with Linear Relational Embeddings (LREs) and Linear Relational Concepts (LRCs) for LLMs in PyTorch
+
+.. image:: https://img.shields.io/pypi/v/linear-relational.svg?color=blue
+   :target: https://pypi.org/project/linear-relational
+   :alt: PyPI
+
+.. image:: https://img.shields.io/github/actions/workflow/status/chanind/linear-relational/ci.yaml?branch=main
+   :target: https://github.com/chanind/linear-relational
+   :alt: Build Status
+
+
+Installation
+------------
+Linear-Relational releases are hosted on `PyPI`_, and can be installed using `pip` as below:
+
+.. code-block:: bash
+
+   pip install linear-relational
+
+This library assumes you're working with PyTorch and Huggingface Transformers.
+
+LREs and LRCs
+-------------
+
+This library provides utilities and PyTorch modules for working with LREs and LRCs. LREs estimate the relation between a subject and object in a transformer language model (LM) as a linear map.
+
+This library assumes you're working with sentences with a subject, relation, and object. For instance, in the sentence: "Lyon is located in the country of France" would have the subject "Lyon", relation "located in country", and object "France". A LRE models a relation like "located in country" as a linear map consisting of a weight matrix :math:`W` and a bias term :math:`b`, so a LRE would map from the activations of the subject (Lyon) at layer :math:`l_s` to the activations of the object (France) at layer :math:`l_o`. So:
+
+.. math::
+   LRE(s) = W s + b
+
+LREs can be inverted using a low-rank inverse, shown as :math:`LRE^{\dagger}`, to estimate :math:`s` from :math:`o`:
+
+.. math::
+   LRE^{\dagger}(o) = W^{\dagger}(o - b)
+
+Linear Relational Concepts (LRCs) represent a concept :math:`(r, o)` as a direction vector $v$ on subject tokens, and can act like a simple linear classifier. For instance, while a LRE can represent the relation "located in country", we could learn a LRC for "located in the country: France", "located in country: Germany", "located in country: China", etc... This is just the result from passing in an object activation into the inverse LRE equation above.
+
+.. math::
+   LRC(o) = W^{\dagger}(o - b)
+
+For more information on LREs and LRCs, check out `these <https://arxiv.org/abs/2308.09124>`_ `papers <https://arxiv.org/abs/2311.08968>`_.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   usage
+   about
+
+.. toctree::
+   :caption: Project Links
+
+   GitHub <https://github.com/chanind/linear-relational>
+   PyPI <https://pypi.org/project/linear-relational>
+
+.. _PyPI: https://pypi.org/project/linear-relational/