Docs Directory (#16)

Updates "example-book" directory to "docs" for more generic use. Closes #9
gw-ospo · May 30, 2024 · 4f08028 · 4f08028
1 parent 3b6878f
commit 4f08028
Show file tree

Hide file tree

Showing 13 changed files with 58 additions and 21 deletions.
diff --git a/.github/workflows/deploy-book.yml b/.github/workflows/deploy-book.yml
@@ -11,8 +11,13 @@ on:
     # unrelated files, you can make this run only if a file within that specific
     # folder has been modified.
     #
-    paths:
-    - example-book/**
+    #paths:
+    #- docs/**
+
+  # make this workflow manually runnable
+  # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch
+  workflow_dispatch:
+
 
 jobs:
   deploy-book:
@@ -32,26 +37,33 @@ jobs:
       run: |
         pip install -r requirements.txt
 
+    # (optional) if you would like to use requirements.txt file inside docs folder
+    #
+    #- name: Install docs dependencies
+    #  run: |
+    #    pip install -r docs/requirements.txt
+
     # (optional) Cache your executed notebooks between runs
     # if you have config:
     # execute:
     #   execute_notebooks: cache
-    - name: cache executed notebooks
-      uses: actions/cache@v3
-      with:
-        path: _build/.jupyter_cache
-        key: jupyter-book-cache-${{ hashFiles('requirements.txt') }}
+    #
+    #- name: cache executed notebooks
+    #  uses: actions/cache@v3
+    #  with:
+    #    path: _build/.jupyter_cache
+    #    key: jupyter-book-cache-${{ hashFiles('requirements.txt') }}
 
     # Save the book's HTML contents to the _build directory
     - name: Build the book
       run: |
-        jupyter-book build example-book/
+        jupyter-book build docs/
 
     # Upload the book's HTML as an artifact
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v2
       with:
-        path: "example-book/_build/html"
+        path: "docs/_build/html"
 
     # Deploy the book's HTML to GitHub Pages
     - name: Deploy to GitHub Pages

diff --git a/README.md b/README.md
@@ -44,49 +44,55 @@ pip install -r requirements.txt
 
 ### Initializing
 
-FYI - the following command was used to create the structure for this book (where "example-book" was chosen as the name of the book):
+FYI - the following command was used to create the structure for this book (where "docs" was chosen as the name of the book):
 
 ```sh
-jupyter-book create example-book
+jupyter-book create docs
 ```
 
 If you have created a copy of this repository, you won't need to repeat this initialization step.
 
 ### Customizing
 
-There are a number of opportunities to customize the book configuration via the ["_config.yml" file](/example-book/_config.yml) (for example, updating the logo). The sidebar navigation can be customized via the ["_toc.yml" file](/example-book/_toc.yml). See the [Jupyter Book Configuration Reference](https://jupyterbook.org/customize/config.html) for more details.
+There are a number of opportunities to customize the book configuration via the ["_config.yml" file](/docs/_config.yml) (for example, updating the logo). The sidebar navigation can be customized via the ["_toc.yml" file](/docs/_toc.yml). See the [Jupyter Book Configuration Reference](https://jupyterbook.org/customize/config.html) for more details.
 
 Also customize the content for your book, adding new markdown and notebook files to your book directory, as desired.
 
 If you are including IPYNB notebooks in your book, and if these notebooks use any third-party Python packages, you must update the ["requirements.txt" file](/requirements.txt) to include the names of those packages.
 
 ### Building
 
-> NOTE: the commands below assume your book is named "example-book", however if you choose a different book name, you'll need to update the commands accordingly
+> NOTE: the commands below assume your book is named "docs", however if you choose a different book name, you'll need to update the commands accordingly
 
-Build book as LaTeX (see "example-book/_build/latex"):
+Build book as LaTeX (see "docs/_build/latex"):
 
 ```sh
-jupyter-book build example-book/ --builder latex
+jupyter-book build docs/ --builder latex
 ```
 
-Build book as PDF (see "example-book/_build/latex/book.pdf"):
+Build book as PDF (see "docs/_build/latex/book.pdf"):
 
 ```sh
-jupyter-book build example-book/ --builder pdflatex
+jupyter-book build docs/ --builder pdflatex
 ```
 
-Build book as HTML: (see "example-book/_build/html/index.html"):
+Build book as HTML: (see "docs/_build/html/index.html"):
 
 ```sh
-jupyter-book build example-book/ --builder html
+jupyter-book build docs/ --builder html
 ```
 
-## Deploying
+Clearing the cache, as necessary:
+
+```sh
+jupyter-book clean docs/ --all
+```
+
+### Deploying
 
 We want to [publish a GitHub Pages site using a GitHub Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow). See also the [Jupyter Book GitHub Pages Guide](https://jupyterbook.org/en/stable/publish/gh-pages.html).
 
-The ["deploy-book.yml" workflow file](/.github/workflows/deploy-book.yml) controls the build process, and has been created for you already. If you use your own book name, customize "example-book" in this file to refer to the book name you chose (see lines 15, 48, and 54).
+The ["deploy-book.yml" workflow file](/.github/workflows/deploy-book.yml) controls the build process, and has been created for you already. If you use your own book name, customize "docs" in this file to refer to the book name you chose (see lines 15, 60, and 66).
 
 By following the "Repo Setup" section above, you will have configured your repository to be hosted on GitHub Pages.
 

diff --git a/example-book/_config.yml → docs/_config.yml b/example-book/_config.yml → docs/_config.yml
diff --git a/example-book/_toc.yml → docs/_toc.yml b/example-book/_toc.yml → docs/_toc.yml
diff --git a/example-book/intro.md → docs/intro.md b/example-book/intro.md → docs/intro.md
diff --git a/example-book/logo.png → docs/logo.png b/example-book/logo.png → docs/logo.png
diff --git a/example-book/markdown-notebooks.md → docs/markdown-notebooks.md b/example-book/markdown-notebooks.md → docs/markdown-notebooks.md
diff --git a/example-book/markdown.md → docs/markdown.md b/example-book/markdown.md → docs/markdown.md
diff --git a/example-book/notebooks.ipynb → docs/notebooks.ipynb b/example-book/notebooks.ipynb → docs/notebooks.ipynb
diff --git a/example-book/ospo-logo.png → docs/ospo-logo.png b/example-book/ospo-logo.png → docs/ospo-logo.png
diff --git a/example-book/references.bib → docs/references.bib b/example-book/references.bib → docs/references.bib
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,17 @@
+
+
+
+# USE JUPYTER BOOK TO BUILD THE BOOK
+# https://jupyterbook.org/en/stable/start/overview.html
+#jupyter-book
+
+# for building with --builder pdfhtml
+#pyppeteer
+
+
+# ALSO ADD ANY PACKAGES THAT YOUR NOTEBOOKS REQURE (BELOW)
+# JUPYER BOOK WILL EXECUTE THE NOTEBOOKS
+# ... SO THEY WILL NEED TO HAVE THEIR PACKAGE DEPENDENCIES SATISFIED
+#matplotlib
+#numpy
+# etc...
diff --git a/requirements.txt b/requirements.txt
@@ -3,6 +3,8 @@
 # https://jupyterbook.org/en/stable/start/overview.html
 jupyter-book
 
+# for building with --builder pdfhtml
+#pyppeteer
 
 # ALSO ADD ANY PACKAGES THAT YOUR NOTEBOOKS REQURE (BELOW)
 # JUPYER BOOK WILL EXECUTE THE NOTEBOOKS