diff --git a/.github/workflows/prs.yaml b/.github/workflows/prs.yaml index ed5a25d..179bbac 100644 --- a/.github/workflows/prs.yaml +++ b/.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 diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 0f1c843..23a2683 100644 --- a/.github/workflows/publish.yml +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a6cb81a..233697b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,14 +4,28 @@ - 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 +37,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. diff --git a/README.md b/README.md index 6445700..54ff189 100644 --- a/README.md +++ b/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/). diff --git a/build-helper.sh b/build-helper.sh index 809d913..0e72af4 100755 --- a/build-helper.sh +++ b/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" diff --git a/source/General/Contacts.md b/source/General/Contacts.md index 6cfd3db..df47c03 100644 --- a/source/General/Contacts.md +++ b/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. diff --git a/source/OSBv1/links.yml b/source/OSBv1/links.yml deleted file mode 100644 index f82e8ec..0000000 --- a/source/OSBv1/links.yml +++ /dev/null @@ -1,2 +0,0 @@ -Research_Themes: "/docs/Research_Themes/" -Background_Information: "docs/Help/Background_Information" diff --git a/source/_config.yml b/source/_config.yml index 3cd0534..4e802a7 100644 --- a/source/_config.yml +++ b/source/_config.yml @@ -10,10 +10,11 @@ logo: images/DARK/OSB logo new dark notext.png bibtex_bibfiles: - Reference/references.bib -# Force re-execution of notebooks on each build. +# Configure notebook execution. # 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