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

Jump to bottom

Highlight web workflow for editing docs #34

Closed
melissawm opened this issue Oct 27, 2022 · 1 comment · Fixed by #157
Closed

Highlight web workflow for editing docs #34

melissawm opened this issue Oct 27, 2022 · 1 comment · Fixed by #157
Labels
content Ideas for new or improved content

Comments

@melissawm
Copy link
Member

See for example #5 (comment)
@melissawm melissawm mentioned this issue Oct 27, 2022
Merged
11 tasks
@melissawm melissawm added the content Ideas for new or improved content label Oct 27, 2022
@melissawm
Copy link
Member Author

Also, from #5 (review)

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.

@seankmartin seankmartin mentioned this issue May 16, 2023
Merged
psobolewskiPhD added a commit that referenced this issue May 25, 2023
@seankmartin @melissawm @psobolewskiPhD
Add more information to the documentation contribution guide (#157)
741829f 
# Description

Adds some more information around the different napari documentation
resources and some more ways to build to the documentation contribution
guide.

Main things:
1. Breaks down the different sources of napari docs and what they are
written in (please let me know if I missed any!)
2. I've tried to highlight how you can contribute to the docs completely
through GitHub if you like with no local setup. I think this would be
great for simple changes and ease barrier to entry.
3. Mentioned the use of extra `make` commands such as `html-noplot` and
`linkcheck-files`.
4. I also modified the makefile slightly to accept filenames to link
check in the `linkcheck-files` command.

This is based on information I've picked up as I've been getting to
grips with how to efficiently contribute to docs.
It is possible some details are slightly inaccurate as a result, so
please let me know if anything I've written is a bit off!

I plan to make another PR at a later date with information about how to
build the docs from Windows using git bash or WSL, but I think it best
not to bloat this PR.

# References

Closes #34 - except for the comment "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."

I've not used jupytext before, so I wouldn't feel too comfortable adding
information about this. I'm not actually sure how running this document
(for example) in Jupyter helps with writing it so I'm very open to input
here! 😄

---------

Co-authored-by: Melissa Weber Mendonça <[email protected]>
Co-authored-by: Peter Sobolewski <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
content Ideas for new or improved content
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add more information to the documentation contribution guide seankmartin/napari-docs
1 participant
@melissawm