chore: update readthedocs config

.readthedocs.yml

@@ -0,0 +1,14 @@
+---
+version: 2
+
+conda:
+  environment: doc/python/environment.yml
+
+sphinx:
+  configuration: doc/python/source/conf.py
+
+build:
+  os: ubuntu-22.04
+  jobs:
+    pre_build:
+      - make clean swig python

Makefile

@@ -361,3 +361,35 @@ $(PROFILE_OBJECT:%=$(PFLDIR)/%): $(PROFILE_SOURCE:%=$(PFLDIR)/%)
 	$(CXX) $(PROFILE_CXXFLAGS) -c $(@:.o=.cpp) -o $@
 
 #############################################################################
+
+
+export UID=$(shell id -u)
+export GID=$(shell id -g)
+
+docs:
+	@$(MAKE) --no-print-directory -C doc/python html
+
+docs-clean:
+	rm -rf doc/python/build
+
+SHELL := /bin/bash
+.ONESHELL:
+docker-docs:
+	set -euxo pipefail
+
+	docker build -t ffpopsim-docs-builder \
+	--network=host \
+	--build-arg UID=$(shell id -u) \
+	--build-arg GID=$(shell id -g) \
+	doc/python
+
+	docker run -it --rm \
+	--network=host \
+	--name=ffpopsim-docs-builder-$(shell date +%s) \
+	--init \
+	--user=$(shell id -u):$(shell id -g) \
+	--volume=$(shell pwd):/home/user/src \
+	--publish=8000:8000 \
+	--workdir=/home/user/src \
+	--env 'TERM=xterm-256colors' \
+	ffpopsim-docs-builder

doc/python/Dockerfile

@@ -0,0 +1,86 @@
+FROM continuumio/miniconda3:23.3.1-0
+
+SHELL ["bash", "-euxo", "pipefail", "-c"]
+
+ARG DEBIAN_FRONTEND=noninteractive
+ARG USER=user
+ARG GROUP=user
+ARG UID
+ARG GID
+
+ENV TERM="xterm-256color"
+ENV HOME="/home/user"
+
+# Install required packages if running Debian or Ubuntu
+RUN set -euxo pipefail >/dev/null \
+&& export DEBIAN_FRONTEND=noninteractive \
+&& apt-get update -qq --yes \
+&& apt-get install -qq --no-install-recommends --yes \
+  apt-transport-https \
+  bash \
+  bash-completion \
+  ca-certificates \
+  curl \
+  git \
+  gnupg \
+  make \
+  sudo \
+>/dev/null \
+&& apt-get clean autoclean >/dev/null \
+&& apt-get autoremove --yes >/dev/null \
+&& rm -rf /var/lib/apt/lists/*
+
+# Make a user and group
+RUN set -euxo pipefail >/dev/null \
+&& \
+  if [ -z "$(getent group ${GID})" ]; then \
+    addgroup --system --gid ${GID} ${GROUP}; \
+  else \
+    groupmod -n ${GROUP} $(getent group ${GID} | cut -d: -f1); \
+  fi \
+&& \
+  if [ -z "$(getent passwd ${UID})" ]; then \
+    useradd \
+      --system \
+      --create-home --home-dir ${HOME} \
+      --shell /bin/bash \
+      --gid ${GROUP} \
+      --groups sudo \
+      --uid ${UID} \
+      ${USER}; \
+  fi \
+&& sed -i /etc/sudoers -re 's/^%sudo.*/%sudo ALL=(ALL:ALL) NOPASSWD:ALL/g' \
+&& sed -i /etc/sudoers -re 's/^root.*/root ALL=(ALL:ALL) NOPASSWD:ALL/g' \
+&& sed -i /etc/sudoers -re 's/^#includedir.*/## **Removed the include directive** ##"/g' \
+&& echo "%sudo ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers \
+&& echo "${USER} ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers \
+&& touch ${HOME}/.hushlogin \
+&& chown -R ${UID}:${GID} "${HOME}"
+
+RUN set -euxo pipefail >/dev/null \
+  && chown -R ${USER}:${GROUP} ${HOME}
+
+COPY environment.yml ${HOME}/src/
+
+WORKDIR ${HOME}/src
+
+RUN set -euxo pipefail >/dev/null \
+  && cd ${HOME}/src \
+  && conda install anaconda-client -n base \
+  && conda env create -f environment.yml --name org.neherlab.ffpopsim.docs
+
+USER ${USER}
+
+RUN set -euxo pipefail >/dev/null \
+  && conda init bash \
+  && echo "conda activate org.neherlab.ffpopsim.docs" >> ${HOME}/.bashrc
+
+ENV PATH="/opt/conda/envs/org.neherlab.ffpopsim.docs/bin:${PATH}"
+
+CMD bash -c "set -euxo pipefail \
+  && source ${HOME}/.bashrc \
+  && make -j8 swig python \
+  && cd doc/python \
+  && rm -rf build \
+  && make autobuild \
+  "

doc/python/Makefile

@@ -1,152 +1,27 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-PAPER         =
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
 BUILDDIR      = build
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
-
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	-rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/FFPopSim.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/FFPopSim.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/FFPopSim"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/FFPopSim"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+.PHONY: help Makefile
 
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+# 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)
 
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
+autobuild:
+	cd source && sphinx-autobuild --host=0.0.0.0 --port=8000 . ../build/html
 
 linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
+	sphinx-build -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck $(SPHINXOPTS) $(O)
 
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."

doc/python/README.md

@@ -0,0 +1,53 @@
+# FFPopSim Python documentation
+
+Readthedocs project for FFPopSim
+
+## Building the docs with Docker (recommended)
+
+Once you have [Docker](https://docs.docker.com/get-docker/) installed, run from the root of the project:
+
+    make docker-docs
+
+The HTML files will appear in `docs/build/html/` (for manual inspection) and served on `http://localhost:8000`. The package `sphinx-autobuild` will watch the files, rebuild the HTML and reload the page in the browser on changes. 
+
+
+## Building the docs locally
+
+Build dependencies are managed with [Conda](https://conda.io).
+
+Enter the docs directory:
+
+    cd doc/python
+
+Install them into an isolated environment named `org.neherlab.ffpopsim.docs` with:
+
+    conda env create
+
+Enter the environment with:
+
+    conda activate org.neherlab.ffpopsim.docs
+
+You can now build the documentation with:
+
+    make html
+
+which invokes Sphinx to build static HTML pages in `doc/python/build/html/`.
+
+On some platforms you can view them in the default browser by running:
+
+    open build/html/index.html
+
+or
+
+    xdg-open build/html/index.html
+
+
+Alternatively, you can run
+
+    make autobuild
+
+The HTML files will also appear in `doc/python/build/html/` (for manual inspection) and served on `http://localhost:8000`. The `sphinx-autobuild` will watch the files, rebuild the HTML and reload the page in the browser on changes.
+
+Leave the environment with:
+
+    conda deactivate

doc/python/environment.yml

@@ -0,0 +1,25 @@
+name: org.neherlab.ffpopsim.docs
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - anaconda-client
+  - boost-cpp==1.82.0
+  - gcc
+  - gcc_linux-64
+  - gsl==2.7
+  - gxx
+  - gxx_linux-64
+  - make==4.3
+  - numpy
+  - pip
+  - recommonmark
+  - requests
+  - sphinx
+  - swig==4.0.2
+  - pip:
+    - sphinx-argparse
+    - sphinx-autobuild
+    - sphinx-markdown-tables
+    - sphinx-rtd-theme
+    - sphinx-tabs