Merge pull request #1802 from hyanwong/jupyter-book

Start conversion of docs to jupyter-book

docs/Makefile

@@ -1,30 +1,24 @@
-# Minimal makefile for Sphinx documentation
-#
 
-# You can set these variables from the command line.
-SPHINXOPTS    = -W --keep-going
-SPHINXBUILD   = python3 -m sphinx
-SOURCEDIR     = .
-BUILDDIR      = _build
+# Need to set PYTHONPATH so that we pick up the local tskit
+PYPATH=$(shell pwd)/../python/
+TSK_VERSION:=$(shell PYTHONPATH=${PYPATH} \
+   python3 -c 'import tskit; print(tskit.__version__.split("+")[0])')
 
+BUILDDIR      = _build
 DOXYGEN_XML=doxygen/xml
 
-all: ${DOXYGEN_XML}
-	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+all: ${DOXYGEN_XML} dev
 
 ${DOXYGEN_XML}: ../c/tskit/*.h
 	cd doxygen && doxygen
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+dev:
+	PYTHONPATH=${PYPATH} ./build.sh
 
-clean:
-	rm -rf $(BUILDDIR) $(DOXYGEN_XML)
+dist:
+	@echo Building distribution for tskit version ${TSK_VERSION}
+	sed -i '' -e s/__TSKIT_VERSION__/${TSK_VERSION}/g _config.yml
+	PYTHONPATH=${PYPATH} ./build.sh
 
-# .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)
+clean:
+	rm -fR $(BUILDDIR) $(DOXYGEN_XML)

docs/_config.yml

@@ -0,0 +1,94 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: Tskit manual
+author: Tskit Developers
+copyright: "2021"
+only_build_toc_files: true
+# logo: logo.png
+
+execute:
+  execute_notebooks: cache
+
+launch_buttons:
+  binderhub_url: ""
+
+repository:
+  url: https://github.com/tskit-dev/tskit
+  branch: main
+  path_to_book: docs
+
+html:
+  use_issues_button: true
+  use_repository_button: true
+  use_edit_page_button: true
+  # Do not edit this - the version placeholder is replaced by the
+  # current version during a distribution build in the Makefile
+  extra_navbar: tskit __TSKIT_VERSION__
+  extra_footer: tskit __TSKIT_VERSION__
+
+sphinx:
+    extra_extensions:
+    - breathe
+    - sphinx.ext.autodoc
+    - sphinx.ext.autosummary
+    - autodocsumm
+    - sphinx.ext.todo
+    - sphinx.ext.viewcode
+    - sphinx.ext.intersphinx
+    - sphinx_issues
+    - sphinxarg.ext
+
+    config:
+      myst_enable_extensions:
+      - colon_fence
+      - deflist
+      - dollarmath
+      - substitution
+      issues_github_path: tskit-dev/tskit
+      todo_include_todos: true
+      intersphinx_mapping:
+        python: ["https://docs.python.org/3/", null]
+        tutorials: ["https://tskit.dev/tutorials/", null]
+        stdpopsim: ["https://stdpopsim.readthedocs.io/en/stable", null]
+        pyslim: ["https://tskit.dev/pyslim/docs/latest/", null]
+        numpy: ["https://numpy.org/doc/stable/", null]
+
+      breathe_projects: {"tskit": "doxygen/xml"}
+      breathe_default_project: "tskit"
+      breathe_domain_by_extension: {"h": "c"}
+      breathe_show_define_initializer: True
+
+      # TODO these are not ignored, see https://github.com/sphinx-doc/sphinx/issues/9748
+      # so currently nitpicky is turned off when building the jupyterbook in build.sh
+      nitpick_ignore: [
+          ["c:identifier", "int32_t"],
+          ["c:identifier", "uint32_t"],
+          ["c:identifier", "uint64_t"],
+          ["c:identifier", "FILE"],
+          ["c:type", "int32_t"],
+          ["c:type", "uint32_t"],
+          ["c:type", "uint64_t"],
+          ["c:type", "bool"],
+          ["py:class", "tskit.metadata.AbstractMetadataCodec"],
+          ["py:class", "tskit.trees.Site"],
+          # TODO these have been triaged here to make the docs compile, but we should
+          # sort them out properly. https://github.com/tskit-dev/tskit/issues/336
+          ["py:class", "array_like"],
+          ["py:class", "row-like"],
+          ["py:class", "array-like"],
+          ["py:class", "dtype=np.uint32"],
+          ["py:class", "dtype=np.uint32."],
+          ["py:class", "dtype=np.int32"],
+          ["py:class", "dtype=np.int8"],
+          ["py:class", "dtype=np.float64"],
+          ["py:class", "dtype=np.int64"],
+      ]
+
+      autodoc_member_order: bysource
+
+      # Without this option, autodoc tries to put links for all return types
+      # in terms of the fully-qualified classnames which we don't want, and also
+      # leads to broken links and nitpick failures. So, until we tackle
+      # typehints fully, this is the simplest approach.
+      autodoc_typehints: none

docs/_static/bespoke.css

@@ -0,0 +1,3 @@
+/* When a code cell outputs tskit tables in plain text, widen the tab size so column
+   contents line up. Invoke this by adding :tags:["output-wide-tabs"] to the cell */
+.tag_output-wide-tabs .cell_output pre {tab-size: 16}

docs/_toc.yml

@@ -0,0 +1,20 @@
+format: jb-book
+root: introduction
+parts:
+- caption: Getting started
+  chapters:
+  - file: installation
+- caption: APIs
+  chapters:
+  - file: python-api
+  - file: c-api
+  - file: stats
+- caption: Miscellaneous
+  chapters:
+  - file: cli
+  - file: data-model
+  - file: metadata
+  - file: combinatorics
+  - file: provenance
+  - file: development
+  - file: changelogs

docs/build.sh

@@ -0,0 +1,20 @@
+#/bin/bash
+
+# Jupyter-build doesn't have an option to automatically show the 
+# saved reports, which makes it difficult to debug the reasons for 
+# build failures in CI. This is a simple wrapper to handle that.
+
+REPORTDIR=${BUILDDIR}/html/reports
+
+jupyter-book build -W --keep-going .
+RETVAL=$?
+if [ $RETVAL -ne 0 ]; then
+    if [ -e $REPORTDIR ]; then
+      echo "Error occured; showing saved reports"
+      cat $REPORTDIR/*
+    fi
+else
+    # Clear out any old reports
+    rm -f $REPORTDIR/*
+fi
+exit $RETVAL

docs/changelogs.rst

@@ -1,3 +1,5 @@
+.. note: this is left in rst format to avoid Duplicate ID issues
+
 .. _sec_changelogs:
 
 ==========

docs/cli.md

@@ -0,0 +1,26 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.12
+    jupytext_version: 1.9.1
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+```{currentmodule} tskit
+```
+
+(sec_cli)=
+
+# Command line interface
+
+```{eval-rst}
+.. argparse::
+    :module: tskit.cli
+    :func: get_tskit_parser
+    :prog: python3 -m tskit
+```