use myst for sphinx docs

qiskit-community · Jan 10, 2024 · baf666e · baf666e
1 parent dbde658
commit baf666e
Show file tree

Hide file tree

Showing 9 changed files with 62 additions and 39 deletions.
diff --git a/README.md b/README.md
@@ -4,13 +4,17 @@ Faster simulations of fermionic quantum circuits.
 
 ## What is ffsim?
 
+<!-- start what-is-ffsim -->
+
 ffsim is a software library for simulating fermionic quantum circuits that conserve particle number
 and the Z component of spin. This category includes many quantum circuits used for quantum chemistry simulations.
 By exploiting the symmetries and using specialized algorithms, ffsim can simulate these circuits much faster
 than a generic quantum circuit simulator.
 
 **Experimental disclaimer**: ffsim is currently an experimental release. Breaking changes may be introduced without warning.
 
+<!-- end what-is-ffsim -->
+
 ## Documentation
 
 Documentation is located at the [project website](https://qiskit-community.github.io/ffsim/).
@@ -23,12 +27,16 @@ ffsim is supported on Linux, macOS, and the Windows Subsystem for Linux (WSL). I
 
 ### From PyPI
 
+<!-- start install-from-pypi -->
+
 ffsim is available on [PyPI](https://pypi.org/project/ffsim/). It can be installed by running the command
 
 ```bash
 pip install ffsim
 ```
 
+<!-- end install-from-pypi -->
+
 ### From source
 
 Installing ffsim from source requires the following system dependencies:

diff --git a/docs/api/index.md b/docs/api/index.md
@@ -0,0 +1,11 @@
+# API Reference
+
+```{toctree}
+
+ffsim
+ffsim.contract
+ffsim.linalg
+ffsim.optimize
+ffsim.random
+ffsim.testing
+```
diff --git a/docs/api/index.rst b/docs/api/index.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -25,6 +25,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.extlinks",
     "sphinx_autodoc_typehints",
+    "myst_parser",
     "nbsphinx",
 ]
 
@@ -49,4 +50,5 @@
 
 # nbsphinx options (for tutorials)
 nbsphinx_timeout = 500
-nbsphinx_execute = "always"
+# TODO change this back to "always"
+nbsphinx_execute = "never"
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,28 @@
+# ffsim
+
+Faster simulations of fermionic quantum circuits.
+
+## What is ffsim?
+
+```{include} ../README.md
+:start-after: <!-- start what-is-ffsim -->
+:end-before: <!-- end what-is-ffsim -->
+```
+
+## Install from PyPI
+
+```{include} ../README.md
+:start-after: <!-- start install-from-pypi -->
+:end-before: <!-- end install-from-pypi -->
+```
+
+## Get started
+
+Check out the [tutorials](tutorials/index.md).
+
+```{toctree}
+:hidden:
+
+tutorials/index
+api/index
+```
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
@@ -0,0 +1,11 @@
+# Tutorials
+
+```{toctree}
+
+01-introduction
+02-orbital-rotation
+03-double-factorized
+04-lucj
+05-entanglement-forging
+06-fermion-operator
+```
diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst
diff --git a/pyproject.toml b/pyproject.toml
@@ -28,6 +28,7 @@ dev = [
     "jupyter-sphinx",
     "maturin",
     "mypy",
+    "myst-parser",
     "nbmake",
     "nbsphinx",
     "pytest",