Skip to content

Update docs contribution guide for two-repo setup#5

Merged
jni merged 5 commits intonapari:mainfrom
melissawm:update-contributor-docs
Dec 12, 2022
Merged

Update docs contribution guide for two-repo setup#5
jni merged 5 commits intonapari:mainfrom
melissawm:update-contributor-docs

Conversation

@melissawm
Copy link
Copy Markdown
Member

@melissawm melissawm commented Oct 14, 2022

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.

@github-actions github-actions bot added the documentation Improvements or additions to documentation label Oct 14, 2022
@melissawm melissawm requested review from DragaDoncila and jni October 14, 2022 21:10
melissawm
melissawm commented Oct 14, 2022
View reviewed changes
jni
jni approved these changes Oct 15, 2022
View reviewed changes
Copy link
Copy Markdown
Member

@jni jni left a comment

Choose a reason for hiding this comment

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

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
Copy link
Copy Markdown
Member

jni commented Oct 15, 2022

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
lucyleeow reviewed Oct 17, 2022
View reviewed changes
Copy link
Copy Markdown
Collaborator

@lucyleeow lucyleeow left a comment

Choose a reason for hiding this comment

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

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

@melissawm
Copy link
Copy Markdown
Member Author

melissawm commented Oct 17, 2022

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

psobolewskiPhD
psobolewskiPhD reviewed Oct 17, 2022
View reviewed changes
psobolewskiPhD
psobolewskiPhD approved these changes Oct 17, 2022
View reviewed changes
lucyleeow
lucyleeow reviewed Oct 18, 2022
View reviewed changes
@melissawm melissawm mentioned this pull request Oct 27, 2022
Closed
@psobolewskiPhD
Copy link
Copy Markdown
Member

psobolewskiPhD commented Oct 27, 2022

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

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

due to #8

@melissawm melissawm added content Ideas for new or improved content and removed documentation Improvements or additions to documentation labels Oct 27, 2022
@melissawm melissawm force-pushed the update-contributor-docs branch from dac1d32 to 932a952 Compare October 28, 2022 19:45
@github-actions github-actions bot added the documentation Improvements or additions to documentation label Oct 28, 2022
@melissawm
Copy link
Copy Markdown
Member Author

melissawm commented Oct 28, 2022

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.

@github-actions github-actions bot added the task label Oct 28, 2022
@melissawm melissawm force-pushed the update-contributor-docs branch from f358847 to f6a4685 Compare October 28, 2022 21:22
@melissawm
Copy link
Copy Markdown
Member Author

melissawm commented Nov 23, 2022

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

psobolewskiPhD
psobolewskiPhD reviewed Nov 27, 2022
View reviewed changes
psobolewskiPhD
psobolewskiPhD approved these changes Nov 27, 2022
View reviewed changes
Copy link
Copy Markdown
Member

@psobolewskiPhD psobolewskiPhD left a comment

Choose a reason for hiding this comment

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

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
Copy link
Copy Markdown
Member Author

melissawm commented Nov 28, 2022

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.

psobolewskiPhD
psobolewskiPhD reviewed Dec 9, 2022
View reviewed changes
@melissawm melissawm force-pushed the update-contributor-docs branch from f6a4685 to 1c7fd37 Compare December 9, 2022 19:25
@jni jni merged commit e634704 into napari:main Dec 12, 2022
@jni
Copy link
Copy Markdown
Member

jni commented Dec 12, 2022

❤️ 🚀

@melissawm melissawm mentioned this pull request Dec 12, 2022
Merged
6 tasks
@aganders3 aganders3 mentioned this pull request Dec 13, 2022
Merged
2 tasks
@psobolewskiPhD psobolewskiPhD added this to the 0.4.18 milestone Jun 22, 2023
@Czaki Czaki modified the milestones: 0.4.18, 0.5.0 Jun 23, 2023
@psobolewskiPhD psobolewskiPhD modified the milestones: 0.5.0, 0.4.19 Oct 24, 2023
@Czaki Czaki modified the milestones: 0.4.19, 0.5.0 Oct 25, 2023
@melissawm melissawm deleted the update-contributor-docs branch January 9, 2024 14:06
@github-actions github-actions bot mentioned this pull request Sep 20, 2025
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Czaki Czaki Czaki left review comments

@lucyleeow lucyleeow lucyleeow left review comments

@psobolewskiPhD psobolewskiPhD psobolewskiPhD approved these changes

@jni jni jni approved these changes

@DragaDoncila DragaDoncila Awaiting requested review from DragaDoncila

Assignees

@melissawm melissawm

Labels

content Ideas for new or improved content documentation Improvements or additions to documentation task

Projects

None yet

Milestone

0.4.19

Development

Successfully merging this pull request may close these issues.

Update contributor docs

5 participants

@melissawm @jni @psobolewskiPhD @Czaki @lucyleeow