Repository: napari/napari

Issue:
Migration proposal between repositories
## 📚 Documentation

Hello, folks

During the latest docs working group and community meetings we have been discussing a strategy to unify documentation for napari in a way that
1. Makes it easier to run doctests and CI
2. Makes it easier for contributors to know where to contribute

### Current situation

As of now, this is the workflow as I understand it:
1. The Tutorials live on the napari.github.io repo, as they were migrated there from the old tutorials repo. See https://github.com/napari/napari.github.io/tree/main/tutorials
2. All the other parts of the documentation live on the main napari repo (the one where this issue lives) and are copied over to napari.github.io via [the `copy-docs.py` script](https://github.com/napari/napari/blob/main/docs/copy-docs.py)
3. This `copy-docs.py` script also generates a `_toc.yml` file that is copied over to napari.github.io, where it is used to generate the napari.org website table of contents.
4. All of the theme and website tooling lives at napari.github.io

### Proposal

The proposal is to move the Tutorial content to the main napari repo and unify the parts of the documentation that are copied over to napari.github.io. This means
- People contributing docs should only post issues and PRs to one repo, napari/napari
- We can run CI on all the docs, including the tutorials
- Anything related to website (design, tooling, infrastructure) should go into napari/napari.github.io

### Notes

- With this strategy, it might be more complicated to get actual documentation previews on napari/napari. Because the docs are built with the theme that lives on another repo, one option might be to have a CI image with a frozen version of the website that is only updated occasionally. Personally, I think that is good enough for docs CI, and I strongly advocate for having some sort of preview when submitting docs content to napari/napari.
- The alternative would be to move all the docs to napari.github.io. This might simplify preview, but the actual API documentation would still need to live on napari/napari and we would have a split anyway.

Does this sound like a reasonable plan? Happy to hear thoughts and concerns.


Discussion:
>  I strongly advocate for having some sort of preview when submitting docs content to napari/napari.

+1 :+1:
This part is hugely important, whichever solution we end up with.


> > I strongly advocate for having some sort of preview when submitting docs content to napari/napari.
> 
> +1 👍 This part is hugely important, whichever solution we end up with.

Pinging @codemonkey800 who may have missed this and has recently been building out a preview page for plugins on the napari-hub. That work has more stringent requirements about the preview not going stale, and is limited to one single HTML page, but we should be able to repurpose some of that work to get similar behavior here.

In particular I think the preview should be "no extra work" on the contributor's part, so a combo GitHub Action + App might work well in this instance.

Or, maybe a better option would be to have a local dev environment, like we do for `napari.github.io` but point it to the napari directory instead? This could potentially be achieved using `make` by grabbing the relevant content from `napari.github.io` and then building the theme using `yarn` on top of `napari/docs`. 
I've opened #3572 to track discussion on docs previews for contributors.
This proposal sounds good to me, I'm glad the docs are finally being consolidated! 
> In particular I think the preview should be "no extra work" on the contributor's part, so a combo GitHub Action + App might work well in this instance.

This would be challenging with our existing setup because we're hosting things on GitHub pages, which do not have built-in support for preview deployments.

Rather than reinvent the wheel, maybe we can leverage existing services under an open source plan? One good example is [Netlify](https://www.netlify.com/legal/open-source-policy) whose open source plan provides features from their pro plan to open source projects. The [preview feature](https://docs.netlify.com/site-deploys/deploy-previews/) would allow us to create preview deployments on PRs so that contributors could preview the docs per PR 

Resolving patch:
diff --git a/docs/copy-docs.py b/docs/copy-docs.py
--- a/docs/copy-docs.py
+++ b/docs/copy-docs.py
@@ -24,11 +24,13 @@
 TO_COPY = [
     'ORGANIZATION.md',
     'glossary.md',
-    'developers',
     'community',
+    'developers',
+    'getting_started',
     'howtos',
     'release',
     'roadmaps',
+    'tutorials',
     'images',
     osp.join('_templates', 'autosummary'),
     *[


Test patch: