Migrating the tutorials to JupyterBook

.gitignore

@@ -12,7 +12,6 @@
 test/test_packages/temp_test_files/*
 *_checkpoints/
 *_checkpoint/
-jupyter_notebooks/**/offline
 test/test_packages/offline
 hooks/etc/permissions.yml
 *comm_output*.txt
@@ -21,9 +20,6 @@ hooks/etc/permissions.yml
 /.eggs/
 .ropeproject
 .vscode
-doc/_autosummary
-doc/autoapi
-doc/build
 .venv*
 *.pyc*
 
@@ -47,26 +43,13 @@ test/test_packages/cmp_chk_files/Fake_Dataset_none.txt.cache
 **.noseids
 **test_ibmq**
 
-# Tutorial Notebook Untracked Files #
-####################################
-jupyter_notebooks/Tutorials/tutorial_files/modeltest_report
-jupyter_notebooks/Tutorials/tutorial_files/gettingStartedReport
-jupyter_notebooks/Examples/example_files/*.pkl
-jupyter_notebooks/Examples/example_files/*.json
-jupyter_notebooks/Examples/example_files/leakage_*
-jupyter_notebooks/Tutorials/tutorial_files/exampleReport
-jupyter_notebooks/Tutorials/tutorial_files/exampleStdReport
-jupyter_notebooks/Tutorials/tutorial_files/exampleMultiEstimateReport
-jupyter_notebooks/Tutorials/tutorial_files/exampleMultiEstimateReport2
-jupyter_notebooks/Tutorials/tutorial_files/exampleMultiDataSetReport
-jupyter_notebooks/Tutorials/tutorial_files/exampleBriefReport
-jupyter_notebooks/Tutorials/tutorial_files/*.ipynb
-jupyter_notebooks/Tutorials/tutorial_files/tempTest
-jupyter_notebooks/Tutorials/tutorial_files/*checkpoints
-jupyter_notebooks/Tutorials/objects/advanced/test_ibmq*
-jupyter_notebooks/Tutorials/tutorial_files/test_mirror_benchmark
-
-
+# Documentation autogenerated #
+###############################
+docs/_autosummary
+docs/_build
+docs/notebooks/**/*.ipynb
+docs/tutorial_files
+docs/example_files
 
 # Compiled source #
 ###################
@@ -122,12 +105,6 @@ Thumbs.db
 .idea/
 HighImpactPaper1/texFiles/.DS_Store
 
-# Generated documentation #
-###########################
-doc/html/*
-doc/_auto
-doc/_build
-
 # Customer Data #
 #################
 scripts/profiling/report/*.ipynb

README.md

@@ -36,7 +36,7 @@ In particular, there are a number of characterization protocols currently implem
 
 PyGSTi is designed with a modular structure so as to be highly customizable
 and easily integrated to new or existing python software.  It runs using
-python 3.9 or higher.  To faclilitate integration with software for running
+python 3.9 or higher.  To facilitate integration with software for running
 cloud-QIP experiments, pyGSTi `Circuit` objects can be converted to IBM's
 **OpenQASM** and Rigetti Quantum Computing's **Quil** circuit description languages.
 
@@ -58,7 +58,7 @@ included in the package will then be buried within your Python's
 
 ~~~
 cd <install_directory>
-git clone https://github.com/pyGSTio/pyGSTi.git
+git clone https://github.com/sandialabs/pyGSTi.git
 cd pyGSTi
 pip install -e .[complete]
 ~~~
@@ -152,45 +152,57 @@ report = pygsti.report.construct_standard_report(results, title="My Report", ver
 report.write_html("myReport", auto_open=True, verbosity=1) # Can also write out Jupyter notebooks!
 ~~~
 
-Tutorials and Examples
-----------------------
+Documentation
+-------------
 There are numerous tutorials (meant to be pedagogical) and examples (meant to be demonstrate
-how to do some particular thing) in the form of Jupyter notebooks beneath the `pyGSTi/jupyter_notebooks`
-directory.  The root "START HERE" notebook will direct you where to go based on what you're most
-interested in learning about.  You can view the
-[read-only GitHub version of this notebook](https://github.com/pyGSTio/pyGSTi/blob/master/jupyter_notebooks/START_HERE.ipynb)
-or you can [explore the tutorials interactively](https://mybinder.org/v2/gh/pyGSTio/pyGSTi/master)
-using JupyterHub via Binder.  Note the existence of a
-[FAQ](https://github.com/pyGSTio/pyGSTi/blob/master/jupyter_notebooks/FAQ.ipynb), which
-addresses common issues.
+how to do some particular thing) in the `pyGSTi/docs` directory. These are stored as MyST Markdown
+for version control convenience, but can be converted to Jupyter notebooks as needed using Jupytext.
+
+#### Viewing the documentation *online*
+The recommended way to view the documentation is on [ReadTheDocs](https://pygsti.readthedocs.io/en/latest/),
+although the raw Markdown files can also be looked at on [GitHub](https://github.com/sandialabs/pyGSTi/blob/master/docs/markdown/intro.md).
+
+When using the ReadTheDocs version, you can [**interactively** explore the tutorials using Binder](https://mybinder.org/v2/gh/sandialabs/pyGSTi/master)
+by clicking the rocket button on the top of any tutorial page. If the document opens in the Markdown version,
+right-click and open as a Notebook to have Jupytext convert it to a runnable notebook.
+
+#### Building the documentation *locally*
+The documentation is built using JupyterBook. Presuming you have `jupytext` and `jupyter-book` installed
+from `pip` and have followed the *local installation* directions above,
+the following command will build all the documentation:
+    ``jb build docs``
 
+Then open `docs/_build/html/index.html` in a web browser to look through the documentation.
 
 #### Running notebooks *locally*
-While it's possible to view the notebooks on GitHub using the links above, it's
-usually nicer to run them *locally* so you can mess around with the code as
-you step through it.  To do this, you'll need to start up a Jupyter notebook
-server using the following steps (this assumes you've followed the *local
-installation* directions above):
+It can also be convenient to build and run the tutorials locally. We can do this using Jupytext
+for conversion and then start a Jupyter notebook or JupyterLab server to run the notebooks.
+Assuming you've followed the *local installation* directions above:
 
-* Changing to the notebook directory, by running:
-    ``cd jupyter_notebooks/Tutorials/``
+* Change to the docs directory, by running:
+    ``cd docs``
 
-* Start up the Jupyter notebook server by running:
-  ``jupyter notebook``
+* Convert the Markdown files to their corresponding notebooks:
+    ``jupytext --sync markdown/**/*.md``
+
+* Change to the newly populated `notebooks` directory:
+    ``cd notebooks``
+
+* Start up the Jupyter notebook server by running ``jupyter notebook`` or a JupyterLab server by running ``jupyter lab``.
 
 The Jupyter server should open up your web browser to the server root, from
-where you can start the first "START_HERE.ipynb" notebook.  Note that the key
+where you can start the first `intro.ipynb` notebook.  Note that the key
 command to execute a cell within the Jupyter notebook is ``Shift+Enter``, not
 just ``Enter``.
 
-
-Documentation
--------------
-Online documentation is hosted on [Read the Docs](http://pygsti.readthedocs.io).
+#### Contributing notebook changes
+Note that only the Markdown files are stored in the repository. If you have made changes to a notebook that
+you wish to push back to the repo, you must run another `jupytext --sync markdown/**/*.md` from the ``docs`` folder
+to resync the Markdown file with the changes you have made in the notebook, and then commit the updated Markdown file.
 
 License
 -------
-PyGSTi is licensed under the [Apache License Version 2.0](https://github.com/pyGSTio/pyGSTi/blob/master/LICENSE).
+PyGSTi is licensed under the [Apache License Version 2.0](https://github.com/sandialabs/pyGSTi/blob/master/LICENSE).
 
 
 Questions?