Merge pull request #289 from pyiron/jupyterbook

Use jupyter book for documentation
pyiron · May 1, 2024 · 07d762b · 07d762b
2 parents 9ac77bd + 9d7bc03
commit 07d762b
Show file tree

Hide file tree

Showing 18 changed files with 50 additions and 213 deletions.
diff --git a/.ci_support/environment-docs.yml b/.ci_support/environment-docs.yml
@@ -13,3 +13,4 @@ dependencies:
 - tqdm =4.66.2
 - pympipool =0.7.18
 - cloudpickle =3.0.0
+- jupyter-book =1.0.0
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -9,10 +9,16 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "mambaforge-22.9"
+  jobs:
+    pre_build:
+      # Generate the Sphinx configuration for this Jupyter Book so it builds.
+      - "cp README.md docs"
+      - "cp notebooks/*.ipynb docs"
+      - "jupyter-book config sphinx docs/"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-  configuration: docs/source/conf.py
+  builder: html
 
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: []
@@ -26,3 +32,5 @@ python:
   install:
     - method: pip
       path: .
+      extra_requirements:
+        - sphinx
diff --git a/README.md b/README.md
@@ -1,18 +1,18 @@
-# pysqa - a simple queue adapter for python
+# pysqa
 
 [![Python package](https://github.com/pyiron/pysqa/workflows/Python%20package/badge.svg)](https://github.com/pyiron/pysqa/actions)
 [![Documentation Status](https://readthedocs.org/projects/pysqa/badge/?version=latest)](https://pysqa.readthedocs.io/en/latest/?badge=latest)
 [![Coverage Status](https://coveralls.io/repos/github/pyiron/pysqa/badge.svg?branch=main)](https://coveralls.io/github/pyiron/pysqa?branch=main)
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pyiron/pysqa/HEAD?labpath=notebooks%2Fexample.ipynb)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pyiron/pysqa/HEAD?labpath=example.ipynb)
 
 High-performance computing (HPC) does not have to be hard. In this context the aim of `pysqa` is to simplify the submission of calculation to an HPC cluster as easy as starting another subprocess locally. This is achieved based on the assumption that even though modern HPC queuing systems offer a wide range of different configuration options, most users submit the majority of their jobs with very similar parameters. 
 
 Therefore, in `pysqa` users define submission script templates once and reuse them to submit many different calculations or workflows. These templates are defined in the [jinja2 template language](https://palletsprojects.com/p/jinja/), so current submission scripts can be easily extended to templates. In addition to the submission of new jobs to the queuing system `pysqa` also allows the users to track the progress of their jobs, delete them or enable reservations using the built-in functionality of the queuing system.
 
-All this functionality is available from both a [Python interface](https://pysqa.readthedocs.io/en/latest/python.html) as well as a [command line interface](https://pysqa.readthedocs.io/en/latest/command.html). 
+All this functionality is available from both a [Python interface](https://pysqa.readthedocs.io/en/latest/example.html) as well as a [command line interface](https://pysqa.readthedocs.io/en/latest/command.html). 
 
 # Features
-The core feature of `pysqa` is the communication to an HPC queuing system ([Flux](https://pysqa.readthedocs.io/en/latest/queue.html#flux), [LFS](https://pysqa.readthedocs.io/en/latest/queue.html#lfs), [MOAB](https://pysqa.readthedocs.io/en/latest/queue.html#moab), [SGE](https://pysqa.readthedocs.io/en/latest/queue.html#sge), [SLURM](https://pysqa.readthedocs.io/en/latest/queue.html#slurm) and [TORQUE](https://pysqa.readthedocs.io/en/latest/queue.html#torque)). This includes: 
+The core feature of `pysqa` is the communication to an HPC queuing system ([Flux](https://pysqa.readthedocs.io/en/latest/queue.html#flux), [LFS](https://pysqa.readthedocs.io/en/latest/queue.html#lfs), [MOAB](https://pysqa.readthedocs.io/en/latest/queue.html#moab), [SGE](hhttps://pysqa.readthedocs.io/en/latest/queue.html#sge), [SLURM](https://pysqa.readthedocs.io/en/latest/queue.html#slurm) and [TORQUE](https://pysqa.readthedocs.io/en/latest/queue.html#torque)). This includes: 
 
 * Submission of new calculation to the queuing system. 
 * List of calculation currently waiting or running on the queuing system. 
@@ -40,11 +40,11 @@ Finally, there is current work in progress to support a combination of [multiple
   * [SGE](https://pysqa.readthedocs.io/en/latest/queue.html#sge)
   * [SLURM](https://pysqa.readthedocs.io/en/latest/queue.html#slurm)
   * [TORQUE](https://pysqa.readthedocs.io/en/latest/queue.html#torque)
-* [Python Interface](https://pysqa.readthedocs.io/en/latest/python.html)
-  * [List available queues](https://pysqa.readthedocs.io/en/latest/python.html#list-available-queues)
-  * [Submit job to queue](https://pysqa.readthedocs.io/en/latest/python.html#submit-job-to-queue)
-  * [Show jobs in queue](https://pysqa.readthedocs.io/en/latest/python.html#show-jobs-in-queue)
-  * [Delete job from queue](https://pysqa.readthedocs.io/en/latest/python.html#delete-job-from-queue)
+* [Python Interface](https://pysqa.readthedocs.io/en/latest/example.html)
+  * [List available queues](https://pysqa.readthedocs.io/en/latest/example.html#list-available-queues)
+  * [Submit job to queue](https://pysqa.readthedocs.io/en/latest/example.html#submit-job-to-queue)
+  * [Show jobs in queue](https://pysqa.readthedocs.io/en/latest/example.html#show-jobs-in-queue)
+  * [Delete job from queue](https://pysqa.readthedocs.io/en/latest/example.html#delete-job-from-queue)
 * [Command Line Interface](https://pysqa.readthedocs.io/en/latest/command.html)
   * [Submit job](https://pysqa.readthedocs.io/en/latest/command.html#submit-job)
   * [Enable reservation](https://pysqa.readthedocs.io/en/latest/command.html#enable-reservation)

diff --git a/binder/postBuild b/binder/postBuild
@@ -3,4 +3,11 @@ mkdir -p /home/jovyan/.local/share/jupyter/kernels/flux
 cp binder/kernel.json /home/jovyan/.local/share/jupyter/kernels/flux
 
 # install pympipool
-pip install . --no-deps --no-build-isolation
+pip install . --no-deps --no-build-isolation
+
+# copy notebooks
+mv notebooks/*.ipynb .
+rm -rf notebooks
+
+# clean up
+rm -rf .ci_support .github binder docs notebooks pysqa pysqa.egg-info tests .coveralls.yml .gitignore .readthedocs.yml CODE_OF_CONDUCT.md LICENSE MANIFEST.in README.md pyproject.toml setup.py build
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -0,0 +1,14 @@
+title: pysqa
+author: Jan Janssen
+logo: images/pyiron-logo.png
+
+execute:
+  execute_notebooks           : off
+
+repository:
+    url                       : https://github.com/pyiron/pysqa
+    path_to_book              : ""
+
+launch_buttons:
+  notebook_interface          : jupyterlab
+  binderhub_url               : https://mybinder.org
diff --git a/docs/_static/pyiron_logo.ico b/docs/_static/pyiron_logo.ico
diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -0,0 +1,9 @@
+format: jb-book
+root: README
+chapters:
+- file: installation.md
+- file: queue.md
+- file: example.ipynb
+- file: command.md
+- file: advanced.md
+- file: debug.md
diff --git a/docs/source/advanced.md → docs/advanced.md b/docs/source/advanced.md → docs/advanced.md
diff --git a/docs/source/command.md → docs/command.md b/docs/source/command.md → docs/command.md
diff --git a/docs/source/debug.md → docs/debug.md b/docs/source/debug.md → docs/debug.md
diff --git a/docs/_static/pyiron-logo.png → docs/images/pyiron-logo.png b/docs/_static/pyiron-logo.png → docs/images/pyiron-logo.png
diff --git a/docs/source/installation.md → docs/installation.md b/docs/source/installation.md → docs/installation.md
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/source/queue.md → docs/queue.md b/docs/source/queue.md → docs/queue.md
diff --git a/docs/source/conf.py b/docs/source/conf.py
diff --git a/docs/source/index.rst b/docs/source/index.rst
diff --git a/docs/source/python.md b/docs/source/python.md