added notebooks in how to section. changed theme

Author: simoneliuzzo

docs/conf.py

@@ -48,12 +48,17 @@
               'sphinx.ext.doctest',
               'sphinx.ext.todo',
               'sphinx.ext.coverage',
-              # 'sphinx.ext.mathjax',
+              'sphinx.ext.mathjax',
               'sphinx.ext.viewcode',
               'sphinx.ext.githubpages',
               'sphinx.ext.napoleon',
               'sphinx.ext.autosectionlabel',
               'sphinx.ext.autosummary',
+             # 'nbsphinx'
+             'myst_nb',
+             # 'sphinx.ext.intersphinx',
+             # 'sphinx_copybutton',
+             # 'sphinx_design'
               ]
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth = 2
@@ -111,7 +116,9 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'classic'
+
+# html_theme = 'classic'
+html_theme = "pydata_sphinx_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -120,11 +127,16 @@
     'collapse_navigation': False,
     'display_version': True,
     'logo_only': True,
-    'navigation_depth': 2,
-    "rightsidebar": "false",
+    'navigation_depth': 6,
+    "rightsidebar": True,
     "relbarbgcolor": "black"
 }
 
+html_sidebars = {
+    "index": [],
+    "common/about": [],
+}
+
 
 # Name of an image file (path relative to the configuration directory)
 # that is the logo of the docs, or URL that points an image file for the logo.
@@ -231,4 +243,17 @@
 # at building time. Here used to have PyQT mocked.
 autodoc_mock_imports = ['PyQt5', 'PyQt5.QtGui', 'PyQt5.QtCore', 'PyQt5.QtWidgets',
                         "matplotlib.backends.backend_qt5agg",
-                        ]
+                        ]
+
+# -- Options for the myst markdown parser ------------------------------------
+
+myst_enable_extensions = [
+    "attrs_inline",
+    "colon_fence",
+    "dollarmath",
+    "replacements",
+    "deflist",
+]
+myst_heading_anchors = 3
+nb_execution_mode = "off" #"auto"
+nb_execution_allow_errors = True

docs/index.rst

@@ -1,11 +1,8 @@
 pyAML documentation
-======================================
-
-.. contents:: Table of Contents
-    :depth: 3
-
+===================
+    
 Introduction
-------------------------
+------------
 
 python Accelerator Middle Layer (pyAML) is a joint technology platform to develop common tools for control, tuning and development of storage rings, beam transport lines and linear accelerators.
 
@@ -20,25 +17,45 @@ With pyAML, it WILL be possible to (the software is at conceptualization stage):
 - many more features 
 
 Installation
-------------------------
+------------
 pip support will be provided later. 
 for the time being: 
 
 git clone https://github.com/python-accelerator-middle-layer/pyaml.git
 
 
+Documentation
+-------------
+
+.. toctree::
+    :maxdepth: 1
+    :caption: How to:
+    :glob:
+
+    Load a configuration file <notebooks/load_configuration>
+    Switch design live <notebooks/live_design>
+    Select a control system <notebooks/control_system>
+
+.. toctree::
+   :caption: Modules:
+   :maxdepth: 1
+   :glob:
+
+   modules/*
+
+
 Collaboration community
 ------------------------
 
 Discussion
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~
 
 `Mattermost <https://mattermost.hzdr.de/accelerator-middle-layer/channels/town-square>`_
 
 (please log in using Helmoltz ID, you will be prompt to access with your own lab/university credentials)
 
 Shared documents
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~
 
 to access the shared documents please ask S.Liuzzo for access rigths. 
 
@@ -48,23 +65,13 @@ https://www.overleaf.com/read/hnrqzhfpbvpp#ef8935
 to be added to editors list please write to S.Liuzzo
 
 Mailing list:
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~
 to be added to the pyAML mailing list please write to S.Liuzzo
 
 
-Documentation
-----------------------
-
-.. toctree::
-   :caption: Modules
-   :maxdepth: 1
-   :glob:
-
-   modules/*
-
 
 Indices and tables
-====================================
+==================
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/requirements.txt

@@ -10,5 +10,6 @@ numpy==2.3.4
 pydantic==2.11.0
 accelerator-toolbox==0.7.1
 matplotlib==3.10.7
-nbsphinx==0.9.7
-ipykernel==7.1.0
+#ipykernel==7.1.0
+myst_nb
+pydata-sphinx-theme