chore: misc fixes

.github/workflows/prs.yaml

@@ -19,9 +19,6 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements-book.txt
-    - name: Disable building jupyter-books
-      run: |
-        sed -i "s/execute_notebooks.*/execute_notebooks: 'off'/" source/_config.yml
     - name: Run jupyter-book
       run: |
         jupyter-book clean ./source

.github/workflows/publish.yml

@@ -19,9 +19,6 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements-book.txt
-    - name: Disable building jupyter-books
-      run: |
-        sed -i "s/execute_notebooks.*/execute_notebooks: 'off'/" source/_config.yml
     - name: Run jupyter-book
       run: |
         jupyter-book clean ./source

CONTRIBUTING.md

@@ -4,14 +4,29 @@
 - Please start each sentence on a new line in the documentation. This allows
   for better diffs and pull requests.
 
-
 ## Building docs locally
 
 The documentation currently uses [Jupyter-book](https://jupyterbook.org/).
-To build the documentation locally, to test before opening Pull Requests for example, a virtual environment can be used:
+To build the documentation locally, to test before opening Pull Requests for example,
+a helper script `./build-helper.sh` is provided which automates the setup and build process.
 
-```
+Run `./build-helper.sh -h` to see all available options.
+
+The most commonly used options are:
+
+- `-c`: create a new virtual environment (in `.venv`) and install the required packages
+- `-b`: build the book, creating the HTML files in `./source/_build/html`
+- `-w`: watch the `source` directory for changes and rebuild automatically (requires `inotifywait`)
+- `-p`: publish the built book to GitHub pages (requires commit access to the repository)
+- `-s`: build the book as a single page HTML file
+- `-m`: build the book as a single page HTML file and convert it to a single Markdown file
+- `-X`: clean the book build files
+
+### Manual setup (alternative to `-c`)
+
+If you prefer to set up the environment manually, you can use a virtual environment:
 
+```
   # Create a new virtual environment
   $ python3 -m venv ./.venv
   # Activate the virtual environment
@@ -23,27 +38,26 @@ To build the documentation locally, to test before opening Pull Requests for exa
   # This will create the HTML files in ./source/_build/html
 ```
 
-
 To deactivate the virtual environment:
 
 ```
-
   $ deactivate
 ```
 
 More information on Python virtual environments can be found in the Python documentation [here](https://docs.python.org/3.9/library/venv.html).
 
+The build helper script will automatically use [uv](https://github.com/astral-sh/uv)
+to create the virtual environment if it is available on your system, falling back
+to `python3 -m venv` otherwise.
+
 ## Publishing the book
 
 The book is published using GitHub pages, using the `ghp-import` tool.
 
 ```
-
-  # Use ghp-import
-  $ ghp-import -n -p -f ./source/_build/html
+  # Use the helper script to publish
+  $ ./build-helper.sh -p
 ```
 
 This will import the HTML files built by `jupyter-book` to the `gh-pages` branch.
 More information on this can be found in the [official documentation](https://jupyterbook.org/publish/gh-pages.html).
-
-A helper script `./build-helper.sh` is present in the repository to assist with these steps.

README.md

@@ -4,14 +4,14 @@
 [![GitHub pull requests](https://img.shields.io/github/issues-pr/OpenSourceBrain/Documentation)](https://github.com/OpenSourceBrain/Documentation/pulls)
 [![GitHub issues](https://img.shields.io/github/issues/OpenSourceBrain/Documentation)](https://github.com/OpenSourceBrain/Documentation/issues)
 [![GitHub Org's stars](https://img.shields.io/github/stars/OpenSourceBrain?style=social)](https://github.com/OpenSourceBrain)
-[![Twitter Follow](https://img.shields.io/twitter/follow/OSBTeam?style=social)](https://twitter.com/OSBTeam)
+[![X Follow](https://img.shields.io/x/follow/OSBTeam?style=social)](https://twitter.com/OSBTeam)
 
 
 Updated documentation for [OpenSourceBrain 2](https://opensourcebrain.org/).
 This documentation uses [Jupyter-book](https://jupyterbook.org/) to allow for the use of interactive Jupyter Notebooks.
 
 # Quick Start
-To build this documentation for browsing the latest version on your local machine see **"Building docs locally"** in [CONTRIBUTING.md](https://github.com/OpenSourceBrain/Documentation/blob/master/CONTRIBUTING.md).
+To build this documentation for browsing the latest version on your local machine see **"Building docs locally"** in [CONTRIBUTING.md](https://github.com/OpenSourceBrain/Documentation/blob/main/CONTRIBUTING.md).
 
 # License
 The documentation is licensed under the [CC-By License](https://creativecommons.org/licenses/by/4.0/).

build-helper.sh

@@ -158,7 +158,7 @@ function usage() {
     echo "OPTIONS:"
     echo
     echo "-h: print help message"
-    echo "-c: create new virtual environment in $VENV and install packages."
+    echo "-c: create new virtual environment in $VENV_DIR and install packages."
     echo "-b: build book"
     echo "-s: build book as a single page html"
     echo "-m: build book as a single page html and generate single page markdown"

source/General/Contacts.md

@@ -30,6 +30,6 @@ Please subscribe to the following (low volume) mailing lists:
 If you have trouble with your account, the administrators are reachable at [info@opensourcebrain.org](mailto:info@opensourcebrain.org).
 
 
-## Follow us on Twitter at @OSBTeam
+## Follow us on X
 
-Please follow us on Twitter at [@OSBTeam](https://twitter.com/OSBTeam) to keep up with updates also.
+Please follow us on X (formerly Twitter) at [@OSBTeam](https://twitter.com/OSBTeam) to keep up with updates also.

source/_config.yml

@@ -12,8 +12,9 @@ bibtex_bibfiles:
 
 # Force re-execution of notebooks on each build.
 # See https://jupyterbook.org/content/execute.html
+# The documentation is currently all Markdown content, so notebooks are not executed.
 execute:
-  execute_notebooks: auto
+  execute_notebooks: off
 
 # Define the name of the latex output file for PDF builds
 latex:
@@ -33,7 +34,6 @@ html:
   use_repository_button: true
   use_edit_page_button: true
   favicon: images/favicon.ico
-  google_analytics_id: "" # To be added
   home_page_in_navbar: false