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

Update docs_deployment.md and add paths to workflow #390

Merged
merged 18 commits into from
Apr 16, 2024
Merged

Update docs_deployment.md and add paths to workflow #390

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
5b9a586
update deploy docs
lucyleeow Apr 6, 2024
cd06916
add file paths
lucyleeow Apr 6, 2024
c817e0a
test check dir
lucyleeow Apr 6, 2024
6d18ee0
add paths
lucyleeow Apr 6, 2024
ccfa869
fix
lucyleeow Apr 7, 2024
97f22b6
fix
lucyleeow Apr 7, 2024
8b96a67
update
lucyleeow Apr 7, 2024
982ef0b
fix
lucyleeow Apr 7, 2024
06124ea
update
lucyleeow Apr 7, 2024
05dbb05
fix
lucyleeow Apr 8, 2024
1d6de6e
fix
lucyleeow Apr 8, 2024
357f0e1
fix
lucyleeow Apr 8, 2024
0fb07f6
Merge branch 'main' into doc_docs
psobolewskiPhD Apr 9, 2024
ef93402
version var
lucyleeow Apr 9, 2024
66d67d9
Merge branch 'doc_docs' of github.com:lucyleeow/docs into doc_docs
lucyleeow Apr 9, 2024
6595871
try
lucyleeow Apr 9, 2024
a21c92f
format;
lucyleeow Apr 9, 2024
8beb95b
Merge branch 'main' into doc_docs
lucyleeow Apr 10, 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
20 changes: 15 additions & 5 deletions .github/workflows/build_and_deploy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
# As much as possible, this file should be kept in sync with
# https://github.com/napari/napari/blob/main/.github/workflows/build_docs.yml
name: Build PR Docs
# and https://github.com/napari/napari/blob/main/.github/workflows/deploy_docs.yml
lucyleeow marked this conversation as resolved.
Show resolved Hide resolved
#
# This workflow is triggered by
# https://github.com/napari/napari/blob/main/.github/workflows/deploy_docs.yml when a
# merge to `main` occurs in napari/napari

name: Build & Deploy PR Docs

on:
push:
Expand All @@ -25,11 +31,13 @@ jobs:
- name: Clone docs repo
uses: actions/checkout@v4
with:
# place in '/home/runner/work/docs/docs/docs'
path: docs # place in a named directory

- name: Clone main repo
uses: actions/checkout@v4
with:
# place in '/home/runner/work/docs/docs/napari'
path: napari # place in a named directory
repository: napari/napari
# ensure version metadata is proper
Expand Down Expand Up @@ -69,6 +77,8 @@ jobs:
GOOGLE_CALENDAR_API_KEY: ${{ secrets.GOOGLE_CALENDAR_API_KEY }}
PIP_CONSTRAINT: ${{ github.workspace }}/napari/resources/constraints/constraints_py3.10_docs.txt
with:
# Runs in '/home/runner/work/docs/docs/docs'
# Built HTML pages in '/home/runner/work/docs/docs/docs/docs/_build/html'
run: make -C docs docs
# skipping setup stops the action from running the default (tiling) window manager
# the window manager is not necessary for docs builds at this time and it was causing
Expand All @@ -86,22 +96,22 @@ jobs:
name: Download & Deploy Artifact
needs: build-and-upload
runs-on: ubuntu-latest
# Working directory: '/home/runner/work/docs/docs'
steps:
- name: Download artifact
uses: actions/download-artifact@v4
with:
name: html
# Downloads to '/home/runner/work/docs/docs/html'
path: html
- name: show files
run: ls -lR
Comment on lines -95 to -96
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I think @Czaki added this in #386 as a sanity check, so have removed, but happy to add back.


- name: get directory name
# if this is a tag, use the tag name as the directory name else dev
run: |
if [[ "${{ github.ref }}" == "refs/tags/"* ]]; then
echo "branch_name=${{ github.ref_name }}" >> $GITHUB_ENV
echo "branch_name=${{ github.ref_name }}" >> $GITHUB_ENV
else
echo "branch_name=dev" >> $GITHUB_ENV
echo "branch_name=dev" >> $GITHUB_ENV
fi

- name: Deploy Docs
Expand Down
29 changes: 14 additions & 15 deletions docs/developers/contributing/documentation/docs_deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,36 +16,35 @@ through several CI workflows detailed below.
- **Workflow file:** [`build_docs.yml`](https://github.com/napari/napari/blob/main/.github/workflows/build_docs.yml)
- **job:** `build-and-upload`
- Pulls in sources from `napari/docs` and builds docs locally. Uploads
artifacts to this repo (`napari/napari`).
- This is triggered on every Pull Request and shows up as a "Build PR
Docs" check on the PR.
artifacts to this repository (`napari/napari`).
- This is triggered on any commit tagged 'v*'.
Copy link
Collaborator Author

@lucyleeow lucyleeow Apr 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

So napari/napari build_docs.yml:

  push:
    branches:
      - docs
    tags:
      - 'v*'
  • we don't have a docs branch in napari/napari (anymore?)?
  • we build and upload the artifact, but I can't workout who/when this is used? The napari/napari deploy_docs.yml workflow just triggers the napari/docs build_and_deploy ? I am guessing by the trigger on version tag that maybe this is used for release versions of docs?

(on that note, we state that napari/docs build_and_deploy.yml always deploys to the dev/ folder. But how do the release version 'vxxx' folders get populated??)

This is confusing! 😅

cc @psobolewskiPhD @melissawm

Copy link
Collaborator Author

@lucyleeow lucyleeow Apr 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Nevermind, I can see how the version docs get uploaded to napari/napari.github.io.

Then I really don't understand what napari/napari build_docs.yml workflow is doing, who uses that artifact?

Copy link
Member

Choose a reason for hiding this comment

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

napari/napari build_docs doesn't run on PRs anymore, we rely on CircleCI. I wasn't sure if that was a conscious effort in the napari/napari CI overhaul, to save runners, or what, but it looks like it was an accident: in the syncing of workflows the branch name was also ported over so it's just never triggered.

I dont even think it's used when releasing docs from a branch (like 0.4.19 didn't use the napari/docs repo, but instead cherry picked over to napari/napari), but I'm not sure.
So I think we could delete it, or make it not run on PR so someone could trigger manually if they wanted.

Copy link
Member

Choose a reason for hiding this comment

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

I think this is a leftover from before the repo split. Unfortunately we have lived in a split state for a while (some work depends on the monorepo setup, some work depends on the two-repo setup) and so a lot of it is very confusing. I've done my best to try and capture the changes but the repo does change faster than I can keep track of I'm afraid 😢

Copy link
Member

Choose a reason for hiding this comment

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

So I took a look at the history and it turns out my first instinct was correct:
the pull_request part was removed when napari/napari CI was reworked:
https://github.com/napari/napari/pull/6156/files#diff-4dfe935b4852393622c2b414783d1d11e1a868fd8485709124d90208fa61ec8b

Also, it can be triggered manually, so it's fine to stay I think.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I'll add this info to the docs :)

Copy link
Member

Choose a reason for hiding this comment

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

I didn't phrase that well. That workflow would work in a branch that is before the repo split, so then there is docs in napari/napari. See: v0.4.19:
https://github.com/napari/napari/tree/v0.4.19x
So for example this PR:
https://github.com/napari/napari/actions/runs/7703963871

Copy link
Collaborator Author

@lucyleeow lucyleeow Apr 8, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Ohhh...I'm not so familiar with releasing from a branch so bear with me.

So when releasing from a branch, you have to make a vxx branch AND a docs_vxx branch? And the napari/napari build_docs will run on pushes to docs* branches and v* tags?

And is the build_docs just used to view the docs to make sure they look okay? Are they used for deployment?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@psobolewskiPhD I've updated the docs to what I think is happening. Please let me know if something is off, thanks!

Copy link
Member

Choose a reason for hiding this comment

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

So when releasing from a branch, you have to make a vxx branch AND a docs_vxx branch? And the napari/napari build_docs will run on pushes to docs* branches and v* tags?

I'm not sure this is all required, but the write up seems fine now.
Hopefully that workflow never gets used again because we release 0.5.0

- **Workflow file:** [`deploy_docs.yml`](https://github.com/napari/napari/blob/main/.github/workflows/deploy_docs.yml)
- **job:** `build-and-deploy`
- Triggers [`deploy_docs.yml`](https://github.com/napari/docs/blob/main/.github/workflows/deploy_docs.yml)
- **job:** `deploy`
- Triggers [`build_and_deploy.yml`](https://github.com/napari/docs/blob/main/.github/workflows/build_and_deploy.yml)
workflow at the [napari/docs](https://github.com/napari/docs) repo.
Waits for results and reports it.
- This is triggered on any commit to the `main` branch on
`napari/napari` (and consequently triggers a new deployment of the
`napari.org` website.)

2. [`napari/docs`](https://github.com/napari/docs)
- **Workflow file:** [`build_docs.yml`](https://github.com/napari/docs/blob/main/.github/workflows/build_docs.yml)
- **Workflow file:** [`build_and_deploy.yml`](https://github.com/napari/docs/blob/main/.github/workflows/build_and_deploy.yml)
- **job:** `build-and-upload`
- Pulls in sources from `napari/napari` and builds docs locally. Uploads
artifacts to this repo (`napari/docs`).
- This is triggered on every Pull Request and shows up as a "Build PR
Docs" check on the PR.
- **Workflow file:** [`deploy_docs.yml`](https://github.com/napari/docs/blob/main/.github/workflows/deploy_docs.yml)
- Pulls in sources from `napari/napari`, builds docs, then uploads as an
artifact named 'html' to this repository (`napari/docs`).
- This is triggered on every Pull Request and shows up as a "Build & Deploy PR
Docs / Build & Uplod Artifact" check on the PR.
- **job:** `build-and-deploy`
lucyleeow marked this conversation as resolved.
Show resolved Hide resolved
- Builds docs locally and deploys resulting artifacts to GitHub pages at
the `gh-pages` branch of [napari/napari.github.io](https://github.com/napari/napari.github.io/tree/gh-pages).
- Downloads the artifact from the `build-and-upload` job and deploys the html
to GitHub pages at the `gh-pages` branch of
[napari/napari.github.io](https://github.com/napari/napari.github.io/tree/gh-pages).
- Always deploys to the `dev/` folder on `napari.github.io` (version
"latest" on the website).
- This is triggered on any commit to the `main` branch on `napari/docs`
- Deployment is triggered by any commit to the `main` branch on `napari/docs`
(and consequently triggers a new deployment of the `napari.org`
website.)

Note that these file are not identical to the `napari/napari` versions.
Note that these files are not identical to the `napari/napari` version.

3. [`napari/napari.github.io`](https://github.com/napari/napari.github.io)
- Contains built documentation files (.html) for all versions in the
Expand Down
Loading