Merge pull request #6 from secondmind-labs/va/fix_docs2

fix documentation

.github/workflows/deploy.yaml

@@ -48,7 +48,6 @@ jobs:
       run: poetry install
     - name: make documentation
       run: |
-        cd docs
         make docs
     - run: |
         TMP_DIR=$(mktemp -d -p $(pwd))

Makefile

@@ -0,0 +1,32 @@
+.PHONY: docs
+
+SUCCESS='\033[0;32m'
+UNAME_S = $(shell uname -s)
+
+PANDOC_DEB = https://github.com/jgm/pandoc/releases/download/2.10.1/pandoc-2.10.1-1-amd64.deb
+
+
+
+docs:  ## Build the documentation
+	@echo "\n=== pip install doc requirements =============="
+	pip install -r docs/docs_requirements.txt
+	pip install --upgrade "Jinja2<3"
+	@echo "\n=== install pandoc =============="
+ifeq ("$(UNAME_S)", "Linux")
+	$(eval TEMP_DEB=$(shell mktemp))
+	@echo "Checking for pandoc installation..."
+	@(which pandoc) || ( echo "\nPandoc not found." \
+	  && echo "Trying to install automatically...\n" \
+	  && wget -O "$(TEMP_DEB)" $(PANDOC_DEB) \
+	  && echo "\nInstalling pandoc using dpkg -i from $(PANDOC_DEB)" \
+	  && echo "(If this step does not work, manually install pandoc, see http://pandoc.org/)\n" \
+	  && sudo dpkg -i "$(TEMP_DEB)" \
+	)
+	@rm -f "$(TEMP_DEB)"
+endif
+ifeq ($(UNAME_S),Darwin)
+	brew install pandoc
+endif
+	@echo "\n=== build docs =============="
+	(cd docs ; make html)
+	@echo "\n${SUCCESS}=== Docs are available at docs/_build/html/index.html ============== ${SUCCESS}"

README.md

@@ -8,6 +8,7 @@
 
 [Documentation](https://secondmind-labs.github.io/markovflow/) |
 [Tutorials](https://secondmind-labs.github.io/markovflow/tutorials.html) |
+[API reference](https://secondmind-labs.github.io/markovflow/autoapi/markovflow/index.html) |
 [Slack](https://join.slack.com/t/secondmind-labs/shared_invite/zt-ph07nuie-gMlkle__tjvXBay4FNSLkw)
 
 ## What does Markovflow do?
@@ -22,7 +23,8 @@ Markovflow uses the mathematical building blocks from [GPflow](http://www.gpflow
 
 ## Getting started
 
-In the [Documentation](https://secondmind-labs.github.io/markovflow/), we have multiple [Tutorials](https://secondmind-labs.github.io/markovflow/tutorials.html) showing the basic functionality of the toolbox.
+In the [Documentation](https://secondmind-labs.github.io/markovflow/), we have multiple [Tutorials](https://secondmind-labs.github.io/markovflow/tutorials.html) showing the basic functionality of the toolbox,
+and a comprehensive [API reference](https://secondmind-labs.github.io/markovflow/autoapi/markovflow/index.html).
 
 
 ## Install Markovflow

docs/Makefile

@@ -8,30 +8,8 @@ SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
-LIB_NAME = markovflow
-SUCCESS='\033[0;32m'
-UNAME_S = $(shell uname -s)
 
-PANDOC_DEB = https://github.com/jgm/pandoc/releases/download/2.10.1/pandoc-2.10.1-1-amd64.deb
-
-# the --per-file-ignores are to ignore "unused import" warnings in __init__.py files (F401)
-# the F403 ignore in gpflux/__init__.py allows the `from .<submodule> import *`
-LINT_FILE_IGNORES = "$(LIB_NAME)/__init__.py:F401,F403 \
-                     $(LIB_NAME)/architectures/__init__.py:F401 \
-                     $(LIB_NAME)/encoders/__init__.py:F401 \
-                     $(LIB_NAME)/experiment_support/__init__.py:F401 \
-                     $(LIB_NAME)/initializers/__init__.py:F401 \
-                     $(LIB_NAME)/layers/__init__.py:F401 \
-                     $(LIB_NAME)/layers/basis_functions/__init__.py:F401 \
-                     $(LIB_NAME)/models/__init__.py:F401 \
-                     $(LIB_NAME)/optimization/__init__.py:F401 \
-                     $(LIB_NAME)/sampling/__init__.py:F401 \
-                     $(LIB_NAME)/utils/__init__.py:F401"
-
-
-
-
-.PHONY: help docs
+.PHONY: help html
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -40,31 +18,8 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 
-
-
-docs:  ## Build the documentation
-	@echo "\n=== pip install doc requirements =============="
-	pip install -r docs_requirements.txt
-	@echo "\n=== install pandoc =============="
-ifeq ("$(UNAME_S)", "Linux")
-	$(eval TEMP_DEB=$(shell mktemp))
-	@echo "Checking for pandoc installation..."
-	@(which pandoc) || ( echo "\nPandoc not found." \
-	  && echo "Trying to install automatically...\n" \
-	  && wget -O "$(TEMP_DEB)" $(PANDOC_DEB) \
-	  && echo "\nInstalling pandoc using dpkg -i from $(PANDOC_DEB)" \
-	  && echo "(If this step does not work, manually install pandoc, see http://pandoc.org/)\n" \
-	  && sudo dpkg -i "$(TEMP_DEB)" \
-	)
-	@rm -f "$(TEMP_DEB)"
-endif
-ifeq ($(UNAME_S),Darwin)
-	brew install pandoc
-endif
-	# Create a .py (percent format with multiline comments) from an .ipynb in the first place:
-	# jupytext --update-metadata '{"jupytext": {"cell_markers": "\"\"\""}}' --to py:percent <name-of-notebook>.ipynb
-	# Convert .py to .ipynb (don't seem to need to --execute? perhaps sphinx-build does it...), then build html:
+html:  ## Build the documentation
 	rm -rf _build
 	rm -rf _autosummary
-	find . -name 'notebooks/*.py' -not -iname '__init__.py' | xargs jupytext --to notebook
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	find . -wholename './notebooks/*.py' -not -iname '__init__.py' | xargs jupytext --to notebook
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/index.rst

@@ -24,7 +24,7 @@
 
 
 Welcome to Markovflow
-==================
+=====================
 
 Markovflow is a research toolbox dedicated to Markovian Gaussian processes.
 
@@ -40,7 +40,7 @@ Getting started
 
 We have provided multiple `Tutorials <tutorials>` showing the basic functionality of the toolbox, and have a comprehensive `API Reference <autoapi/markovflow/index>`.
 
-As a quick teaser, here's a snippet from the `intro notebook <notebooks/intro>` that demonstrates how to perform classic GP regression for a simple one-dimensional dataset:
+As a quick teaser, here's a snippet that demonstrates how to perform classic GP regression for a simple one-dimensional dataset:
 
 
 .. code-block:: python

markovflow/models/sparse_pep.py

@@ -30,7 +30,7 @@
 from markovflow.kernels import SDEKernel
 from markovflow.likelihoods import PEPGaussian, PEPScalarLikelihood
 from markovflow.mean_function import MeanFunction, ZeroMeanFunction
-from markovflow.models import MarkovFlowSparseModel
+from markovflow.models.models import MarkovFlowSparseModel
 from markovflow.models.pep import gradient_correction
 from markovflow.models.variational_cvi import back_project_nats
 from markovflow.posterior import ConditionalProcess, PosteriorProcess

markovflow/models/sparse_variational_cvi.py

@@ -25,7 +25,7 @@
 from markovflow.conditionals import conditional_statistics
 from markovflow.kernels import SDEKernel
 from markovflow.mean_function import MeanFunction, ZeroMeanFunction
-from markovflow.models import MarkovFlowSparseModel
+from markovflow.models.models import MarkovFlowSparseModel
 from markovflow.models.variational_cvi import (
     back_project_nats,
     gradient_transformation_mean_var_to_expectation,