From 741829fdf90c06d0593baaa183a95f152e35bac4 Mon Sep 17 00:00:00 2001 From: Sean Martin Date: Thu, 25 May 2023 21:45:18 +0100 Subject: [PATCH] Add more information to the documentation contribution guide (#157) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # 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 Co-authored-by: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> --- Makefile | 2 +- docs/developers/documentation/index.md | 148 ++++++++++++++++++------- 2 files changed, 107 insertions(+), 43 deletions(-) diff --git a/Makefile b/Makefile index 1e5f2770a..5635adf4c 100644 --- a/Makefile +++ b/Makefile @@ -58,4 +58,4 @@ html-noplot: clean prep-docs NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -D plot_gallery=0 -b html docs/ docs/_build -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS) linkcheck-files: - NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -b linkcheck -D plot_gallery=0 --color docs/ docs/_build -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) + NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -b linkcheck -D plot_gallery=0 --color docs/ docs/_build ${FILES} -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS) diff --git a/docs/developers/documentation/index.md b/docs/developers/documentation/index.md index e65dc3a18..238ab5bd2 100644 --- a/docs/developers/documentation/index.md +++ b/docs/developers/documentation/index.md @@ -6,37 +6,86 @@ documentation. ## Organization of the documentation -The napari documentation is built from sources located at the -[napari/docs](https://github.com/napari/docs) repository on GitHub. That -repository is where all the narrative documentation (e.g. tutorials, how-to -guides) pull requests should be made. Meanwhile, changes to docstrings or to the -[examples gallery](https://napari.org/gallery) should be made to the +The napari documentation is built from multiple sources that are organized into repositories: +1. The main napari documentation is built from sources located at the +[napari/docs](https://github.com/napari/docs) repository on GitHub. +That repository is where all the narrative documentation (e.g. tutorials, how-to +guides, etc. on napari.org) pull requests should be made. +This narrative napari documentation is written in +[MyST markdown](https://myst-parser.readthedocs.io/en/latest/index.html), +a version of [commonmark](https://spec.commonmark.org/) Markdown +(see a [markdown cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)) +with some additional features. +2. Some of the documentation about [plugins](https://napari.org/plugins) resides in +the [napari/npe2](https://github.com/napari/npe2) repository +(e.g. the [contributions reference page](https://napari.org/plugins/contributions.html)) and should be modified there. +This is documentation is written with [Jinja](https://jinja.palletsprojects.com/en/3.1.x/). +3. The [examples gallery](https://napari.org/gallery) is generated from Python source files and changes to the gallery should be made to the [napari/napari](https://github.com/napari/napari) repository (see also -[](add-examples)). - -## Prerequisites +[the guide on adding examples to the gallery](add-examples)). +4. Changes to how [napari.org](https://napari.org/dev) appears site-wide are made to the +[napari-sphinx-theme](https://github.com/napari/napari-sphinx-theme). +5. The [API reference documentation](https://napari.org/dev/api/index.html) is autogenerated from the napari source code docstrings. +Docstrings are written in the [reStructuredText format](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) +and any modifications to them should be submitted to the [napari/napari](https://github.com/napari/napari) repository. + +(contributing-without-local-setup)= +## Contributing to the napari documentation without a local setup + +If you would like to see new documentation added to napari or want to see changes to existing documentation, but are not clear on these instructions or don't have the time to write it yourself, you can [open an issue](https://github.com/napari/docs/issues/new/choose). + +If you are adding new documentation or modifying existing documentation and would prefer a simpler workflow than the local setup guide described below, +you can use the GitHub web interface to open your pull request +by either [uploading file(s) from your computer](https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository), +[creating and editing a new file](https://docs.github.com/en/repositories/working-with-files/managing-files/creating-new-files) +or [editing an existing file](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) +on the [napari-docs](https://github.com/napari/docs) GitHub repository. +It's best if you first [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the [napari-docs](https://github.com/napari/docs) repository to your own GitHub account, create a [feature branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#creating-a-branch), upload/create/edit files through the GitHub web interface, and then [open a pull request from your fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) back to [napari-docs](https://github.com/napari/docs). + +You will also be able to [preview the documentation](use-ci-artifacts) as it would appear on [napari.org](https://napari.org/dev) by +using the `Check the rendered docs here!` action at the bottom of your PR which will go to a preview site on [CircleCI](https://circleci.com/). +A member of the maintenance +team will help with updating the [napari.org](https://napari.org/dev) table of contents where necessary (by placing a reference to your new file in [docs/_toc.yml](update-toc)) and making sure your documentation has built correctly. + +(prerequisites)= +## Prerequisites for a local setup to contribute to the napari documentation Prerequisites depend on the type of contribution you wish to make. In general, you will require: -- Some familiarity with [`git`](https://git-scm.com); +- Some familiarity with [`git`](https://git-scm.com). - A [GitHub](https://github.com) account. +```{note} +The napari documentation is built using `make` which does not work on paths which contain spaces. +It is important that you clone the `napari/docs` repository to a path that does not contain spaces. +For example, `C:\Users\myusername\Documents\GitHub\napari-docs` is a valid path, but \ +`C:\Users\my username\Documents\GitHub\napari-docs` is not. +``` + You should first [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) -and clone the [napari/napari](https://github.com/napari/napari) and the [napari/docs](https://github.com/napari/docs) repo to your -machine. Next, navigate to your local clone of the `napari/docs` repository: +and then clone the [napari/napari](https://github.com/napari/napari) and the [napari/docs](https://github.com/napari/docs) repositories to your +machine. To clone these repositories, you can follow any of the options in the [GitHub guide to cloning](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) (if you run into issues refer to [the troubleshooting guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors)). +We recommend installing the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli/about-github-cli) as it is easy to set up repository access permissions from the GitHub CLI and it comes with additional upside, such as the ability to checkout pull requests. +After installing the `GitHub CLI` you can run: ```bash -git clone git@github.com:/docs.git napari-docs -cd napari-docs/ +gh repo clone /napari +gh repo clone /docs napari-docs ``` ````{note} To reduce confusion and possible conflicts, the `docs` fork is being cloned into a local repository folder named `napari-docs`. Alternately, you could also -rename the repository when forking `napari/docs`. +rename the repository when forking `napari/docs` to `napari-docs` and then clone it via `gh repo clone /napari-docs`. ```` +Next, navigate to your local clone of the `napari/docs` repository: + +```bash +cd napari-docs/ +``` + Since the API reference documentation (autogenerated from the napari code docstrings) and the example gallery are sourced from the `napari/napari` repository, before you can build the documentation locally, you need: - a clean `conda` environment; @@ -48,7 +97,7 @@ This setup, with these dependencies, will allow you to preview your document loc ## 0. Before you start If you'd like to contribute a brand new document to our usage section, it might -be worth [opening an issue](https://github.com/napari/napari/issues/new?assignees=&labels=documentation&template=documentation.md&title=) +be worth [opening an issue](https://github.com/napari/docs/issues/new/choose) on our repository first to discuss the content you'd like to see and get some early feedback from the community. The napari team can also suggest what type of document would be best suited, and whether there are already existing documents @@ -63,7 +112,7 @@ want to contribute. The paths are listed in parentheses below. detailed, reproducible step by step guides, usually combining multiple napari features to complete a potentially complex task - [**How-tos**](../../howtos/index) (in [`napari/docs/howtos`](https://github.com/napari/docs/tree/main/docs/howtos)): simple step by step guides demonstrating the use of common features -- [**Getting started**](../../tutorials/start_index) (in [`napari/docs/tutorials/fundamentals`](https://github.com/napari/docs/tree/main/docs/tutorials/fundamentals): +- [**Getting started**](../../tutorials/start_index) (in [`napari/docs/tutorials/fundamentals`](https://github.com/napari/docs/tree/main/docs/tutorials/fundamentals)): these documents are a mix of tutorials and how-tos covering the fundamentals of installing and working with napari for beginners The [**Examples gallery**](../../gallery) sources are in the [main `napari/napari` repository](https://github.com/napari/napari/tree/main/examples) @@ -107,24 +156,26 @@ Run `jupytext your-notebook.ipynb --to myst` to create a new MyST version of you `your-notebook.md`. Edit this file to include the relevant sections from the docs template. ``` +```{admonition} How to check for broken links +:class: tip + +If you have modified lots of document links, you can check that they all work by running `make linkcheck-files` in the `napari/docs` folder. However, this can take a long time to run, so if you have only modified a links in a single document, you can run: + +```bash +make linkcheck-files FILES=path/to/your/document.md +``` + ### Next steps Depending on the type of contribution you are making, you may be able to skip some steps: -* If you are adding new documentation and would prefer a simpler workflow, - you can you can use the - [GitHub web interface to open your pull request](https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository). - A member of the maintenance - team will help with updating TOC and making sure your documentation has built - correctly. You will also be able to preview the documentation yourself by - downloading the built documentation via a link provided by a comment from the - `github-actions` bot. * If you are amending an existing document you can skip straight to [Step #3 - Preview your document](#3-preview-your-document) * For all other documentation changes, follow the steps below. -## 2. Update TOC +(update-toc)= +## 2. Update the table of contents (TOC) If you are adding a new documentation file, you will need to add your document to the correct folder based on its content (see the [list above](#0-before-you-start) @@ -194,26 +245,46 @@ If your documentation change includes code, it is important that you ensure the code is working and executable. This is why you will need to have a development installation of napari installed. [Examples](gallery) are automatically executed when the documentation is built and code problems can -also be caught when previewing the built documentation. If your documentation -change does not include code, you only need the napari docs dependencies -installed. +also be caught when previewing the built documentation. -There are two ways you can preview the documentation website: by building +There are two ways you can build and preview the documentation website as it would appear on [napari.org](https://napari.org): by building locally, or downloading the GitHub Actions built documentation when you submit your pull request. +```{tip} +To see the markdown document structure and content change in real-time without building, you can use a MyST markdown preview tool like [VScode](https://code.visualstudio.com/) with the [MyST extension](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) or [MyST live preview](https://myst-parser.readthedocs.io/en/latest/live-preview.html#). This can also help you to spot any markdown formatting errors that may have occurred. However, this MyST markdown preview will have some differences to the final built html documentation due to autogeneration, so it is still important to build and preview the documentation before submitting your pull request. +``` + ### 3.1. Building locally To build the documentation locally from scratch, run `make docs` from the root of your local clone of the `napari/docs` repository (assuming you've installed -the [docs prerequisites](#prerequisites)). +the [docs prerequisites](prerequisites)). ```bash make docs ``` +If the changes you have made to documentation don't involve changing the napari gallery, +you can speed up this build by running `make html-noplot` instead. This will skip the +gallery build, which involves launching up napari and rendering all the examples. + +```bash +make docs-install +make html-noplot +``` + +The rendered HTML will be placed in `docs/_build`. Find `index.html` in this +folder and drag it into a browser to preview the website with your new document. +You can also run this Python one-liner to deploy a quick local server on +[http://localhost:8000](http://localhost:8000): + +```shell +$ python3 -m http.server --directory docs/_build +``` + ````{note} -The `make docs` command above assumes your have a local clone of the +The `make docs` command above assumes you have a local clone of the [`napari/napari`](https://github.com/napari/napari) repo at the same level as the `napari/docs` clone. If that's not the case, you can specify the location of the examples gallery folder by executing @@ -244,16 +315,8 @@ make docs GALLERY_PATH=../../napari/examples ```` -The rendered HTML will be placed in `docs/_build`. Find `index.html` in this -folder and drag it into a browser to preview the website with your new document. -You can also run this Python one-liner to deploy a quick local server on -[http://localhost:8000](http://localhost:8000): - -```shell -$ python3 -m http.server --directory docs/_build -``` - -````{tip} +````{admonition} Update documentation on file change +:class: tip There's another `make` task you can use for live previews while editing docs: ```shell @@ -285,6 +348,7 @@ This will prevent all but the first napari window from being shown during the do build. ```` +(use-ci-artifacts)= ### 3.2. Use the CI artifacts Alternatively, when you submit your pull request, the napari docs repository @@ -331,7 +395,7 @@ $ python3 -m http.server Once you have written and previewed your document, it's time to open a pull request to [napari's docs repository](https://github.com/napari/docs) and contribute it to our codebase. If you are simply contributing one file (e.g., a tutorial or how-to page) you -can use the [GitHub web interface to open your pull request](https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository). Ensure you +can use the [GitHub web interface to open your pull request](https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository). Ensure your document is added to the correct folder based on its content (see the [list above](#0-before-you-start) for common locations).