setup documentation for coix (#14)

.github/workflows/pytest_and_autopublish.yml

@@ -16,8 +16,9 @@ jobs:
       with:
         python-version: '3.10'
 
+    - run: sudo apt install -y pandoc gsfonts
     - run: pip --version
-    - run: pip install -e .[dev,oryx]
+    - run: pip install -e .[dev,doc,oryx]
     - run: pip freeze
 
     - name: Lint with pylint
@@ -26,6 +27,8 @@ jobs:
       run: pyink --check .
     - name: Lint with isort
       run: isort --check .
+    - name: Build documentation
+      run: make docs
 
   pytest-job:
     needs: lint

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+
+sphinx:
+   configuration: docs/conf.py
+
+formats:
+   - pdf
+   - epub
+
+python:
+   install:
+   - requirements: docs/requirements.txt

Makefile

@@ -15,4 +15,7 @@ lint: FORCE
 test: lint FORCE
 	pytest -vv -n auto
 
+docs: FORCE
+	$(MAKE) -C docs html
+
 FORCE:

README.md

@@ -1,6 +1,7 @@
 # coix
 
 [![Unittests](https://github.com/jax-ml/coix/actions/workflows/pytest_and_autopublish.yml/badge.svg)](https://github.com/jax-ml/coix/actions/workflows/pytest_and_autopublish.yml)
+[![Documentation Status](https://readthedocs.org/projects/coix/badge/?version=latest)](https://coix.readthedocs.io/en/latest/?badge=latest)
 [![PyPI version](https://badge.fury.io/py/coix.svg)](https://badge.fury.io/py/coix)
 
 Inference Combinators in JAX (Coix) is a machine learning framework used to

coix/api.py

@@ -16,6 +16,7 @@
 
 The implement is pretty much backend-agnostic. We just assume that the core
 backend supports the following functionality:
+
   + `suffix(p)`: rename latent variables of the program `p`,
   + `traced_evaluate(p, latents=None)`: execute `p` and collect trace, metrics,
     optionally we can substitute values in `latents` to `p`,
@@ -41,14 +42,14 @@
 
 
 def compose(q2, q1, suffix=True):
-  """Executes q2(*q1(...)).
+  r"""Executes q2(\*q1(...)).
 
   Note: We only allow at most one of `q1` or `q2` is weighted.
 
   Args:
     q2: a program
     q1: a program
-    suffix: whether to add suffix `_PREV_` to variables in `q1`
+    suffix: whether to add suffix `\_PREV\_` to variables in `q1`
 
   Returns:
     q: the composed program
@@ -62,7 +63,7 @@ def wrapped(*args, **kwargs):
 
 
 def extend(p, f):
-  """Executes f(*p(...)) with random variables in f marked as auxiliary.
+  r"""Executes f(\*p(...)) with random variables in f marked as auxiliary.
 
   Note: We don't allow recursively marginalize out `p` yet.
 

docs/Makefile

@@ -0,0 +1,27 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -W
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = coix
+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
+	git clean -dfx build
+	git clean -dfx examples
+	git clean -dfx tutorials
+	git clean -f getting_started.rst
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	git clean -dfx examples
+	git clean -dfx tutorials
+	git clean -f getting_started.rst

docs/_templates/breadcrumbs.html

@@ -0,0 +1,28 @@
+{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
+
+{% set display_vcs_links = display_vcs_links if display_vcs_links is defined else True %}
+
+{% block breadcrumbs_aside %}
+  <li class="wy-breadcrumbs-aside">
+    {% if hasdoc(pagename) and display_vcs_links %}
+      {% if display_github %}
+        {% if check_meta and 'github_url' in meta %}
+          <!-- User defined GitHub URL -->
+          <a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+        {% else %}
+          {% if 'examples/index' in pagename %}
+            <a href="https://github.com/jax-ml/coix/blob/main/examples/README.rst" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+          {% elif 'examples/' in pagename %}
+            <a href="https://github.com/jax-ml/coix/blob/main/{{ pagename }}.py" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+          {% else %}
+            <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+          {% endif %}
+        {% endif %}
+      {% elif show_source and source_url_prefix %}
+        <a href="{{ source_url_prefix }}{{ pagename }}{{ suffix }}">{{ _('View page source') }}</a>
+      {% elif show_source and has_source and sourcename %}
+        <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> {{ _('View page source') }}</a>
+      {% endif %}
+    {% endif %}
+  </li>
+{% endblock %}

docs/algo.rst

@@ -0,0 +1,5 @@
+Inference algorithms
+====================
+
+.. automodule:: coix.algo
+   :members:

docs/api.rst

@@ -0,0 +1,5 @@
+Program combinators
+===================
+
+.. automodule:: coix.api
+   :members: