Update docs contribution guide for two-repo setup

[melissawm]

Description

Updates the docs contribution guide to match the new documentation setup.

Also some light copyediting of the content.

Type of change

• Bug-fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

References

Closes #3

How has this been tested?

• example: the test suite for my feature covers cases x, y, and z
• example: all tests pass with my change

Final checklist:

• My PR is the minimum possible work for the desired functionality
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• If I included new strings, I have used trans. to make them localizable.
  For more information see our translations guide.

[jni]

I'm happy to merge as-is, but wanted to make a couple of notes — could be fixed here or in follow-up PRs:

• I wasn't sure how to update the examples dir in the sphinx configuration, so currently the docs build actions manually copy the examples directory into this repo. Since this PR updates the sphinx config, perhaps it's worth updating the action as well? Or it might be worth splitting out that configuration update into a separate PR?
• I think many docs changes will be fine to make in the GH interface or a plaintext editor, but a really nice feature of jupytext is that it allows you to run the .md files from a Jupyter Lab or Jupyter Notebook interface. This is one of the main reasons why we went with myst-md rather than plain notebooks. I think we should explicitly encourage this way of writing docs, including a final clear+run-all, as the preferred mode of contribution. Again, this could be done in a follow-up.

[jni]

Or it might be worth splitting out that configuration update into a separate PR?

Update: Just saw that this was done in #6. 🙏 But the deploy action and the action on the main repo still need to be updated.

[lucyleeow]

Just a quick look, thanks for doing this, it looks great!

[melissawm]

Thanks for the reviews folks - I will get to it as soon as possible.

[psobolewskiPhD]

Build is failing because of the change noted here:
#5 (comment)
Need:

sphinx_gallery_conf = {
    'examples_dirs': '../examples',

due to #8

[melissawm]

Ok - I think this is a reasonable solution. If you clone both repos next to each other, nothing has changed and you can simply use make docs. But if you want to specify the examples gallery location, you can use

$ make docs GALLERY_PATH=<your path>

The github workflow has been updated accordingly as well.

[melissawm]

Hi folks, any feedback on the proposed solution here? @psobolewskiPhD @jni

[psobolewskiPhD]

Just to be clear, if I have this:

~/dev/napari/napari
~/dev/docs/docs

then everything works without the env var, but if I have some other combo, then need the env var?

[melissawm]

Just to be clear, if I have this:

~/dev/napari/napari
~/dev/docs/docs

then everything works without the env var, but if I have some other combo, then need the env var?

Yes - the current relevant snippet from the Makefile is

ifeq ($(GALLERY_PATH),)
GALLERY_PATH := ../../napari/examples
endif

So if the repos are cloned "next to each other", all should be good.

[jni]

❤️ 🚀