diff --git a/_config.yml b/_config.yml index 570b091..bc75471 100644 --- a/_config.yml +++ b/_config.yml @@ -20,9 +20,9 @@ html:
Powered by Jupyter Book.
repository: - url: https://github.com/SCENE-Collaboration/Code_and_Documentation_Guidelines #change me + url: https://github.com/AdaptiveMotorControlLab/WorkspaceTemplate #change me path_to_book: docs branch: main launch_buttons: - colab_url: "https://colab.research.google.com/github/SCENE-Collaboration/Code_and_Documentation_Guidelines/examples/yourdemo.ipynb" + colab_url: "https://colab.research.google.com/github.com/AdaptiveMotorControlLab/WorkspaceTemplate/examples/yourdemo.ipynb" diff --git a/_toc.yml b/_toc.yml index 256c418..d897b21 100644 --- a/_toc.yml +++ b/_toc.yml @@ -1,5 +1,6 @@ format: jb-book root: docs/StyleGuide +logo: docs/logo.png parts: - caption: Main Documentation chapters: diff --git a/docs/HowTo_JupyterBook.md b/docs/HowTo_JupyterBook.md index 1f407bc..1404e82 100644 --- a/docs/HowTo_JupyterBook.md +++ b/docs/HowTo_JupyterBook.md @@ -1,6 +1,8 @@ # What is Jupyterbook? -https://jupyterbook.org/en/stable/intro.html +We use JupyterBook for documentation and sharing computational notebooks. [Here](https://www.nature.com/articles/d41586-018-07196-1) is a nice article for motivation. + +📑 The documentation: https://jupyterbook.org/en/stable/intro.html ## Quick start @@ -9,7 +11,7 @@ https://jupyterbook.org/en/stable/intro.html jupyter-book create --cookiecutter YourClonedRepo/ ``` -### Build from the template provided +## OR Build from the template provided in this Repo! (1) Use and adapt the two template files (_toc.yml, _config.yml) to your main code base, and be sure to keep the `docs` structure, i.e., ``` @@ -26,11 +28,17 @@ jupyter-book create --cookiecutter YourClonedRepo/ TL;DR in the main repo run: ```python -❯ jupyter-book build . +jupyter-book build . ``` and then follow terminal prompt (check errors, etc)- viola! +## Deployment: + To then deploy the book live, see: https://jupyterbook.org/en/stable/publish/gh-pages.html#automatically-host-your-book-with-github-actions -In short, you will set up a git action to deploy to a new branch (that you never merge) called `gh-pages` +In short, Go to Settings > Pages and set up anaction to deploy to a new branch (that you never merge) called `gh-pages`: + +![Screen Shot 2025-06-17 at 2 20 19 PM](https://github.com/user-attachments/assets/17d13802-6543-4859-ac09-7abbd491277d) + + diff --git a/docs/StyleGuide.md b/docs/StyleGuide.md index 9b75f39..68ccd7a 100644 --- a/docs/StyleGuide.md +++ b/docs/StyleGuide.md @@ -5,7 +5,7 @@ Please see our overall guide on code & project formatting [here](https://github.com/AdaptiveMotorControlLab/WorkspaceTemplate/blob/main/README.md). -### Main Principles 🔨 Organize your code & data : +### Main Principles 🔨 Organize your code & data: - For experimental and ML projects, please use [DataJoint/databases](https://www.datajoint.com/) - Be sure you work under a lab repo, typically called "https://github.com/AdaptiveMotorControlLab/YourName_workspace". - For larger projects (DLC, CEBRA, ExperimentalPipelines, you should be sure your "final" work gets into a pipeline; talk to Mackenzie about this) diff --git a/docs/images/logo.png b/docs/images/logo.png new file mode 100644 index 0000000..b3d795a Binary files /dev/null and b/docs/images/logo.png differ diff --git a/docs/intro b/docs/intro deleted file mode 100644 index 94139a3..0000000 --- a/docs/intro +++ /dev/null @@ -1,41 +0,0 @@ -# Introduction - -This is the intro to the JupyterBook! - -This is just a placeholder for you to document your package. - - -## Developer Guide - -### 0. Edit your `config` and `toc` to your specs. - -### 1. Set Organization-level Permissions (already done for SCENE) -Go to: -`Org Settings` → `Actions` → `General` → `Select the repo` → Check: - -"Allow GitHub Actions to access the GITHUB_TOKEN with write permissions" must be enabled. - -"Workflow permissions" must allow read and write by default, or per repo. - - - -### 2. Deploy the Docs - -First, this is done via the GitHub actions `publish-book.yml`. - -To get a public `github.io` link, you must enable GitHub Pages. -Note, this only works for public repos, or if private, from paid org. - -### Steps: - -1. Go to your repo → **Settings** → **Pages** -2. Under **"Source"**, select: - - * **Branch**: e.g., `main` - * **Folder**: `/_build/html` -3. Click **"Save"** - -GitHub will deploy your book and show a link like: -`https://.github.io//` - -Deployment may take a minute. Refresh the page to see the live link!