Merge pull request #2 from python-accelerator-middle-layer/tutorials

Adding tutorials for creating and inspecting accelerator

Author: TeresiaOlsson

.github/workflows/deploy-pages.yml

@@ -27,10 +27,10 @@ jobs:
         with:
           python-version: "3.11"
 
-      - name: Install docs dependencies
+      - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r docs-requirements.txt
+          pip install -r requirements.txt -r docs/requirements.txt
 
       - name: Build Sphinx docs
         run: ./build-docs.sh

README.md

@@ -4,35 +4,40 @@ The documentation follows the [Diataxis approach](https://diataxis.fr/).
 
 ## Building the Docs
 
-1. Create a virtual environment and activate it.
-2. Install the requirements with `pip install -r docs-requirements.txt`.
-3. Create a new branch. The main branch is protected so you can't push to it directly.
-4. Build the docs locally with `./build-docs.sh`. The new version is available in `docs/build/html/index.html`.
-5. When the local version looks good, push your changes and make a pull request. Pushes to main will build and deploy the new version.
+1. Clone the repository
+2. Create a virtual environment and activate it.
+3. Install the requirements with `pip install -r requirements.txt -r docs/requirements.txt`.
+4. Create a new branch. The main branch is protected so you can't push to it directly.
+5. Build the docs locally with `./build-docs.sh`. The new version is available in `docs/build/html/index.html`.
+6. When the local version looks good, push your changes and make a pull request. Pushes to main will build and deploy the new version.
 
 For the notebooks it is necessary to have the required pyAML packages installed in the environment.
-If you add a new dependency remember to also add it in the requirements.txt or it will not be built correctly.
+If you add a new dependency remember to also add it in the `docs/requirements.txt` or it will not be built correctly.
 
-## Where to Place Content
+## Developing Content
 
 Content should be placed in these categories:
 
 #### [Tutorials](https://diataxis.fr/tutorials/)
 
 A tutorial is a practical activity where learning is done by doing something meaningful towards an achievable goal.
-The purpose is not to get something done but to help to learn.
+The purpose is not to get something done but to help to learn. It should be structured as a lesson. The recommended format is to use a Jupyter notebook.
 
-It should be structured as a lesson. The recommended format is to use a Jupyter notebook.
+The tutorials are rendered using `sphinx-gallery`. They need to be written as a `.py` file using `rst` and not directly as Jupyter notebooks. You can use `jupytext` to make the workflow easier.
 
-#### [How-to guides](https://diataxis.fr/how-to-guides/)
+Jupytext can be used in the terminal but if you are using an IDE there are extensions available which makes it easier. In VS Code install `Jupytext for Notebooks (congyiwu)`. You should then be able to right click on a `.py` file and choose `Open as a Jupyter Notebook`. You can run and modify the notebook as normal and the changes should happen in the `.py` automatically. Just remember that `sphinx-gallery` requires `rst` while notebooks use `markdown` so comments might not be rendered exactly the same.
+
+To create a new tutorial you can start to write it as a notebook and then use the functionality to convert to `.py`. If you have written comments as markdown you need to manually convert them to `rst`.
+
+#### [How-to Guides](https://diataxis.fr/how-to-guides/)
 
 How-to guides help to get something done in the correct and safe way.
 The focus should be on how to achieve a specific task.
 
 Details of the difference between tutorials or how-to guides can be found at https://diataxis.fr/tutorials-how-to/#tutorials-how-to 
 if you are unsure where to place your content.
 
-#### [Technical reference](https://diataxis.fr/reference/)
+#### [Technical Reference](https://diataxis.fr/reference/)
 
 Technical references are technical descriptions of the software, for example the API.
 

build-docs.sh

@@ -2,7 +2,10 @@
 
 set -euo pipefail
 
-rm -rf docs/build .jupyter_cache
+rm -rf docs/source/tutorials docs/source/sg_execution_times.rst
+rm -rf docs/build
+rm -rf .jupyter_cache
+
 mkdir -p docs/source/_static
 
 sphinx-build -E -a -b html docs/source docs/build/html

docs-requirements.txt

@@ -0,0 +1,3 @@
+pyaml-test-lattice==0.1.0a2
+git+https://github.com/python-accelerator-middle-layer/pyaml.git@main
+pyaml-cs-oa[tango] @ git+https://github.com/python-accelerator-middle-layer/pyaml-cs-oa.git@main

docs/requirements.txt

@@ -11,3 +11,31 @@ a.gh-link:visited {
 .sphx-glr-download-zip {
   display: none;
 }
+
+/* Change the number of columns in the sphinx gallery grid */
+/* .sphx-glr-thumbnails {
+  grid-template-columns: 1fr;
+  gap: 1rem;
+} */
+
+.sphx-glr-signature {
+  display: none;
+}
+
+/* Modifications to show the output as in a notebook */
+.sphx-glr-script-out::before {
+  display: none !important;
+  content: none !important;
+}
+
+.sphx-glr-script-out,
+.sphx-glr-script-out div.highlight,
+.sphx-glr-script-out pre {
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+}
+
+.sphx-glr-script-out pre {
+  padding: 0;
+}

docs/source/_static/create_accelerator.png

@@ -1,3 +1,5 @@
+from sphinx_gallery.sorting import FileNameSortKey
+
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -31,26 +33,30 @@
 ]
 
 sphinx_gallery_conf = {
-    "examples_dirs": "tutorials_src",
-    "gallery_dirs": "tutorials",
+    "examples_dirs": ["../tutorials"],
+    "gallery_dirs": ["tutorials"],
+    "filename_pattern": r"\.py$",
+    "show_memory": False,
+    "remove_config_comments": True,
+    "min_reported_time": 999999,
+    "within_subsection_order": FileNameSortKey("../tutorials"),
 
     # Binder (cloud notebook)
     "binder": {
         "org": "python-accelerator-middle-layer",
         "repo": "documentation",
         "branch": "main",
         "binderhub_url": "https://mybinder.org",
-        "dependencies": ["../../requirements.txt"],
+        "dependencies": ["../requirements.txt"],
         "use_jupyter_lab": True,
     },
 }
 
-exclude_patterns += [
-    "tutorials/*.ipynb",
+exclude_patterns = [
     "tutorials/*.py",
+    "tutorials/*.ipynb",
     "tutorials/*.zip",
     "tutorials/*.codeobj.json",
-    "tutorials_src/GALLERY_HEADER.rst"
 ]
 
 # -- Options for HTML output -------------------------------------------------
@@ -67,4 +73,6 @@
 }
 html_theme_options = {
     "secondary_sidebar_items": ["page-toc","sg_download_links", "sg_launcher_links"],
+    "pygments_light_style": "default",
+    "pygments_dark_style": "monokai",
 }