Update docs_deployment.md and add paths to workflow

[lucyleeow]

• Update docs_deployment.md now that we unified workflows in Unify docs workflows #348.
• Change workflow name to be Build & Deploy PR Docs, since Unify docs workflows #348
• Add file paths to the workflow to aid other working on it

[lucyleeow]

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

[psobolewskiPhD]

I made some small suggestions to clarify the current state.
Edit:
I can't suggest but in 1. napari/napari it's also out-dated.

1. build_docs.yaml is not triggered on PR anymore, just circleCI
2. the triggered workflow is the unified one build_and_deploy.yml

[lucyleeow]

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

[lucyleeow]

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?

[psobolewskiPhD]

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.

[melissawm]

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 😢

[psobolewskiPhD]

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.

[lucyleeow]

I'll add this info to the docs :)

[psobolewskiPhD]

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

[lucyleeow]

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?

[lucyleeow]

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

[psobolewskiPhD]

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

[lucyleeow]

Build is failing with:

ImportError: lxml.html.clean module is now a separate project lxml_html_clean.
Install lxml[html_clean] or lxml_html_clean directly.

I thought this was fixed in napari/napari#6799 ?

[psobolewskiPhD]

I was just about to say. It was added to [testing] which is in [dev]
let me look

[lucyleeow]

We do:

docs/.github/workflows/build_and_deploy.yml

Line 50 in 1c6155f

python -m pip install "napari/[all]"

So I guess the fix won't work until a release? Or do we want to install napari dev in that workflow...?

[psobolewskiPhD]

Well, we tell people they need a dev install of napari. But what does the workflow do:

docs/.github/workflows/build_and_deploy.yml

Line 50 in 1c6155f

python -m pip install "napari/[all]"