Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Display Jupyter Notebooks #145

Open
wants to merge 30 commits into
base: master
Choose a base branch
from
Open

Display Jupyter Notebooks #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
537116a
Render jupyter notebooks on handbook
kabilar Apr 19, 2024
c9af0bb
Pin mkdocs-jupyter version to prior release
kabilar Apr 19, 2024
ad635d1
Pin psutil version
kabilar Apr 19, 2024
5408d26
Fix syntax
kabilar Apr 19, 2024
0070b38
Update publishdocs workflow
kabilar Apr 20, 2024
e754aa1
Update workflow
kabilar Apr 20, 2024
d8dc74d
[WIP] Update workflow
kabilar Apr 20, 2024
b1b3f61
Update workflow
kabilar Apr 20, 2024
620d0bb
Update Actions fork
kabilar Apr 20, 2024
24d71b4
Remove testing steps from workflow
kabilar Apr 20, 2024
3f816ac
Update path
kabilar Apr 20, 2024
7656f37
List contents of directory
kabilar Apr 20, 2024
9aebe82
Update example-notebooks location
kabilar Apr 20, 2024
2023693
Move example-notebooks directory
kabilar Apr 20, 2024
bebfd90
Add notebooks to navigation
kabilar Jul 1, 2024
a40f988
Remove test command
kabilar Jul 1, 2024
6039a84
Update format
kabilar Jul 1, 2024
2ddfc7d
Merge branch 'master' of https://github.com/dandi/handbook into noteb…
kabilar Jul 19, 2024
ef70744
Deployed 2ddfc7d with MkDocs version: 1.5.3
kabilar Jul 19, 2024
2e6b4c5
Deployed 2ddfc7d with MkDocs version: 1.5.3
kabilar Jul 19, 2024
d98d2a5
Revert "Deployed 2ddfc7d with MkDocs version: 1.5.3"
kabilar Jul 19, 2024
935322a
Revert "Deployed 2ddfc7d with MkDocs version: 1.5.3"
kabilar Jul 19, 2024
85cc517
Fix paths
kabilar Jul 19, 2024
73f225f
Fix paths
kabilar Jul 19, 2024
22ed99b
Update GitHub Action
kabilar Jul 19, 2024
30f570c
Fix syntax
kabilar Jul 19, 2024
aa7bf66
Revert change since the Action is now updated
kabilar Jul 19, 2024
b4db6d5
Revert `psutil` pin
kabilar Jul 19, 2024
3a14d37
Update GHA fork
kabilar Jul 19, 2024
3035943
Revert Actions since contribution is merged
kabilar Jul 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .github/workflows/build-docs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ name: Build MkDocs
on:
push:
pull_request:
workflow_dispatch:

jobs:
build:
Expand All @@ -10,6 +11,11 @@ jobs:
- name: Checkout repository
uses: actions/checkout@v1

- name: Copy example-notebooks repository
run: |
git clone https://github.com/dandi/example-notebooks
mv ./example-notebooks ./docs/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just to include them as a git submodule? that would disambiguate which version we are to render/include (e.g. we might want to avoid some recent one for some reason etc).

cons:

  • would require "explicit" commit to update to new version, but "explicit is better than implicit", so could indeed still be a github workflow which would do that

WDYT?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually prefer this. We use submodules in PyNWB and it's been a headache requiring special clone syntax. This is simpler and easier.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its been a while since I have used submodules so happy to look into it. I filed an issue (#148) to perhaps expedite this pull request.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it is quite easy really, let me know if you need a hand with that.

It is just that without using them we would get "fluctuating" results of the doc build - it would depend on current version which has its pluses and minuses:

  • +: we would always be "up to date" with notebooks repo since we would always use current master
  • -: as a result we might get sporadic docs build failures if something in current state of notebooks would trigger failing their rendering/inclusion
    • and it would require then adjusting build script to point to specific commit etc making it "hidden"

but in either of the cases, in the long run we better also trigger rebuilding of the handbook whenever notebooks collection change.

  • without git submodule -- it would be matter of just triggering rebuild workflow
  • with git submodule -- it would require PR or at least a commit to update the state of the submodule.

So overall, let's may be proceed without submodules and see where we end up ;-)


- name: Install version of Python
uses: actions/setup-python@v5
with:
Expand Down
6 changes: 6 additions & 0 deletions .github/workflows/publishdocs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ on:
push:
branches:
- master
workflow_dispatch:

jobs:
build:
Expand All @@ -12,6 +13,11 @@ jobs:
- name: Checkout master
uses: actions/checkout@v1

- name: Copy example-notebooks repository
run: |
git clone https://github.com/dandi/example-notebooks
mv ./example-notebooks ./docs/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if included as submodule, would remove duplication of URL spec/action to get it here ...


- name: Deploy docs
uses: mhausenblas/mkdocs-deploy-gh-pages@master
env:
Expand Down
10 changes: 10 additions & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,13 @@ nav:
- REST API Swagger: https://api.dandiarchive.org/swagger
- REST API Redoc: https://api.dandiarchive.org/redoc
- DANDI Hub: "50_hub.md"
- Tutorials:
- DANDI User Guide, Part I: "example-notebooks/dandi/DANDI User Guide, Part I.ipynb"
- DANDI User Guide, Part II: "example-notebooks/dandi/DANDI User Guide, Part II.ipynb"
- Simple Dandiset Search: "example-notebooks/tutorials/neurodatarehack_2024/simple_dandiset_search.ipynb"
- Advanced Asset Search: "example-notebooks/tutorials/cosyne_2023/advanced_asset_search.ipynb"
- Streaming and interacting with NWB data: "example-notebooks/tutorials/bcm_2024/analysis-demo.ipynb"
- NWB Widget Demo: "example-notebooks/demos/NWBWidget-demo.ipynb"
- Health Status:
- Dandisets: https://github.com/dandi/dandisets-healthstatus
- Services: https://www.dandiarchive.org/upptime
Expand All @@ -60,6 +67,9 @@ markdown_extensions:
plugins:
- search
- open-in-new-tab
- mkdocs-jupyter:
ignore_h1_titles: True
include: ["*.ipynb"]

# Customize theme
extra:
Expand Down
1 change: 1 addition & 0 deletions requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
mkdocs-material>=9.5.10
pymdown-extensions
mkdocs-open-in-new-tab
mkdocs-jupyter
Loading