Merge pull request #173 from Tigul/jupyter-books

Jupyter books

.github/workflows/reusable-sphinx-build.yml → .github/workflows/reusable-jupyter-book-build.yml

@@ -1,4 +1,4 @@
-name: Build Sphinx documentation 📖
+name: Build Jupyter-Book documentation 📖
 
 on:
   push:
@@ -18,8 +18,8 @@ defaults:
 
 jobs:
   test-and-build:
-    name: Build Sphinx documentation
-    runs-on: ubuntu-20.04
+    name: Build Jupyter-Book  documentation
+    runs-on: ubuntu-22.04
 
     steps:
 
@@ -33,20 +33,20 @@ jobs:
 
       # ----------------------------------------------------------------------------------------------------------------
 
-      - name: Install PyCRAM dependencies 🍼
+      - name: Install Jupyter-Book  dependencies 🍼
         uses: py-actions/py-dependency-install@v4
         with:
           path: "requirements.txt"
 
       # ----------------------------------------------------------------------------------------------------------------
-      - name: Install Sphinx dependencies 📚
+      - name: Install Jupyter-Book  dependencies 📚
         uses: py-actions/py-dependency-install@v4
         with:
           path: "doc/requirements.txt"
 
       # ----------------------------------------------------------------------------------------------------------------
-      - name: Build Sphinx documentation 📝
+      - name: Build Jupyter-Book  documentation 📝
         working-directory: ./doc
         run: |
-          sudo apt install pandoc
-          make html
+          cd source
+          jupyter-book build .

.readthedocs.yaml

@@ -1,13 +1,29 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
 version: 2
 
+# Set the OS, Python version and other tools you might need
 build:
-  os: "ubuntu-20.04"
+  os: ubuntu-22.04
   tools:
-    python: "3.8"
+    python: "3.9"
+  apt_packages:
+    - graphviz
+  jobs:
+    pre_build:
+      # Generate the Sphinx configuration for this Jupyter Book so it builds.
+      - "jupyter-book config sphinx doc/source"
 
 python:
-    install:
-      - requirements: doc/requirements.txt
+  install:
+    - requirements: doc/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+      - sphinx
 
-submodules:
-  exclude: all
+sphinx:
+  builder: html

doc/README.md

@@ -7,17 +7,24 @@ the instructions below.
 ## Building the documentation
 
 
-The documentation uses sphinx as engine.
-Building sphinx based documentations requires `pandoc <https://pandoc.org/installing.html>`_
-to be installed. Pandoc can be installed via the Ubunutu package manager:
+The documentation uses jupyter-book as engine. Building the documentation requires Python 3.9 or higher to avoid 
+dependency conflicts. On Ubuntu 20.04 you can install Python 3.9 with the following commands.
 ~~~
-sudo apt install pandoc
+apt-get install python3.9
 ~~~
-After installing pandoc, install sphinx on your device.
 
+It is recommended to create a virtual environment to avoid conflicts with the system python interpreter.
 ~~~
-sudo apt install python3-sphinx
+apt-get install python3.9-virtualenv
+virtualenv -p python3.9 --system-site-packages build-doc
 ~~~
+
+Activate the virtual environment.
+~~~
+source build-doc/bin/activate
+~~~
+
+
 Install the requirements in your python interpreter.
 
 ~~~
@@ -26,10 +33,11 @@ pip install -r requirements.txt
 Run pycram and build the docs.
 
 ~~~
-make html
+cd doc/source 
+jupyter-book build .
 ~~~
 Show the index.
 
 ~~~
-firefox build/html/index.html
+firefox _build/html/index.html
 ~~~