You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# napari docs
2
2
3
-
This repository contains the sources for the napari documentation. This includes tutorials, how-tos, the examples gallery and the autogenerated API documentation extracted from the source code docstrings.
3
+
This repository contains the sources for the napari documentation. This includes tutorials, how-tos and other narrative documentation. The autogenerated API documentation is extracted from the source code docstrings, which live on https://github.com/napari/napari
- Familiarity with Jupyter notebooks (code cells and markdown cells)
30
-
- Familiarity with using napari through a Jupyter notebook
54
+
See the [contributor guide](dev-installation) for details. You should have
55
+
[Jupyter notebook](https://jupyter.org/) installed. Familiarity with Jupyter
56
+
notebooks (code cells and markdown cells) as well as using napari through a
57
+
Jupyter notebook is recommended.
31
58
32
59
## 0. Before you start
33
60
34
-
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=)
35
-
on our repository first to discuss the content you'd like to see and get some early feedback from the community.
36
-
The napari team can also suggest what type of document would be best suited, and whether there are already
37
-
existing documents that could be expanded to include the content you think is lacking.
61
+
If you'd like to contribute a brand new document to our usage section, it might
62
+
be worth [opening an issue](https://github.com/napari/napari/issues/new?assignees=&labels=documentation&template=documentation.md&title=)
63
+
on our repository first to discuss the content you'd like to see and get some
64
+
early feedback from the community. The napari team can also suggest what type of
65
+
document would be best suited, and whether there are already existing documents
66
+
that could be expanded to include the content you think is lacking.
38
67
39
-
Go to your local napari folder to find examples of documents you might want to contribute. The paths are listed in parentheses below.
68
+
Go to your local `napari/docs` folder to find examples of documents you might
69
+
want to contribute. The paths are listed in parentheses below.
40
70
41
-
-[**Explanations**](../../guides/index) (in [`napari/docs/guides`](https://github.com/napari/napari/tree/main/docs/guides)):
71
+
- [**Explanations**](../../guides/index) (in [`napari/docs/guides`](https://github.com/napari/docs/tree/main/docs/guides)):
42
72
in depth content about napari architecture, development choices and some complex features
43
-
-[**Tutorials**](../../tutorials/index) (in [`napari/docs/tutorials`](https://github.com/napari/napari/tree/main/docs/tutorials)):
73
+
- [**Tutorials**](../../tutorials/index) (in [`napari/docs/tutorials`](https://github.com/napari/docs/tree/main/docs/tutorials)):
44
74
detailed, reproducible step by step guides, usually combining multiple napari features to complete a potentially complex task
45
-
-[**How-tos**](../../howtos/index) (in [`napari/docs/howtos/`](https://github.com/napari/napari/tree/main/docs/howtos)):
75
+
- [**How-tos**](../../howtos/index) (in [`napari/docs/howtos/`](https://github.com/napari/docs/tree/main/docs/howtos)):
46
76
simple step by step guides demonstrating the use of common features
47
-
-[**Examples**](../../gallery) (in [`napari/examples/`](https://github.com/napari/napari/tree/main/examples)):
48
-
code examples of how to use napari
49
-
-[**Getting started**](../../tutorials/start_index) (in [`napari/docs/tutorials/fundamentals`](https://github.com/napari/napari/tree/main/docs/tutorials/fundamentals):
77
+
- [**Getting started**](../../tutorials/start_index) (in [`napari/docs/tutorials/fundamentals`](https://github.com/napari/docs/tree/main/docs/tutorials/fundamentals):
50
78
these documents are a mix of tutorials and how-tos covering the fundamentals of installing and working with napari for beginners
51
79
80
+
The [**Examples gallery**](../../gallery) sources are in the [main `napari/napari` repository](https://github.com/napari/napari/tree/main/examples)
81
+
and show code examples of how to use napari.
82
+
52
83
```{admonition} Got materials for a workshop?
53
84
:class: tip
54
85
55
-
If you already have teaching materials e.g. recordings, slide decks or jupyter notebooks
86
+
If you already have teaching materials e.g. recordings, slide decks or Jupyter notebooks
56
87
hosted somewhere, you can add links to these on our [napari workshops](../../further-resources/napari-workshops.md) page.
57
88
```
58
89
59
90
## 1. Write your documentation
60
91
61
-
Fork and clone [our repository](https://github.com/napari/napari). If you are
62
-
amending existing documentation, you can do so in your preferred text editor.
63
-
If you wish to add a new tutorial or a how-to, we recommend you use our
64
-
[template](./docs_template).
65
-
66
-
Our goal is that all tutorials and how-tos are easily downloadable and executable by our users.
67
-
This helps ensure that they are reproducible and makes them easier to maintain.
68
-
We therefore provide a notebook template for our documents. Inside the template
69
-
you'll find handy tips for taking screenshots of the viewer, hiding code cells,
70
-
using style guides and what to include in the required prerequisites section.
71
-
72
-
[Jupyter notebooks](https://jupyter.org/) are a great option for our documents, because they allow you to easily combine code and well formatted text in markdown.
73
-
However, their [raw JSON format](https://numpy.org/numpy-tutorials/content/pairing.html#background) is not great for version control, so we use [MyST Markdown](https://myst-parser.readthedocs.io/en/latest/) documents in our repository and on napari.org.
74
-
75
-
Make a copy of `napari/docs/developers/documentation/docs_template.md`.
76
-
You can edit the template directly in Jupyter notebook, or in your preferred text editor.
92
+
Our goal is that all tutorials and how-tos are easily downloadable and
93
+
executable by our users. This helps ensure that they are reproducible and makes
94
+
them easier to maintain. [Jupyter notebooks](https://jupyter.org/) are a great
95
+
option for our documents, because they allow you to easily combine code and well
96
+
formatted text in markdown and can be executed automatically. However, their
is not great for version control, so we use [MyST Markdown](https://myst-parser.readthedocs.io/en/latest/)
99
+
documents in our repository and on [napari.org](https://napari.org).
100
+
101
+
If you are amending existing documentation, you can do so in your preferred text
102
+
editor. If you wish to add a new tutorial or a how-to, we recommend you use our
103
+
[template](./docs_template). Inside the template you'll find handy tips for
104
+
taking screenshots of the viewer, hiding code cells, using style guides and what
105
+
to include in the required prerequisites section.
106
+
107
+
To use the template, make a copy of `docs/developers/documentation/docs_template.md`
108
+
and rename it to match your content. You can edit the template directly in
109
+
Jupyter notebook, or in your preferred text editor.
77
110
78
111
```{admonition} Already have a notebook?
79
112
:class: tip
@@ -92,24 +125,25 @@ some steps:
92
125
93
126
* If you are adding new documentation and would prefer a simpler workflow,
94
127
you can you can use the
95
-
[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
128
+
[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).
129
+
A member of the maintenance
96
130
team will help with updating TOC and making sure your documentation has built
97
131
correctly. You will also be able to preview the documentation yourself by
98
132
downloading the built documentation via a link provided by a comment from the
99
-
'github-actions' bot.
133
+
`github-actions` bot.
100
134
* If you are amending an existing document you can skip straight
101
135
to [Step #3 - Preview your document](#3-preview-your-document)
102
-
* For all other documentation changes, follow the steps below
136
+
* For all other documentation changes, follow the steps below.
103
137
104
138
## 2. Update TOC
105
139
106
140
If you are adding a new documentation file, you will need to add your document
107
141
to the correct folder based on its content (see the [list above](#0-before-you-start)
108
-
for common locations), and update `napari/docs/_toc.yml`.
142
+
for common locations), and update `docs/_toc.yml`.
109
143
110
144
If you're adding a document
111
145
to an existing group, simply add a new `- file:` entry in the appropriate spot. For example, if I wanted to add
112
-
a `progress_bars.md` how to guide, I would place it in `napari/docs/howtos` and update `_toc.yml` as below:
146
+
a `progress_bars.md` how to guide, I would place it in `docs/howtos` and update `_toc.yml` as below:
113
147
114
148
```yaml
115
149
- file: howtos/index
@@ -135,7 +169,7 @@ subtrees:
135
169
```
136
170
137
171
To create a new subheading, you need a `subtrees` entry. For example, if I wanted to add `geo_tutorial1.md` and `geo_tutorial2.md`
138
-
to a new `geosciences` subheading in tutorials, I would place my documents in a new folder `napari/docs/tutorials/geosciences`,
172
+
to a new `geosciences` subheading in tutorials, I would place my documents in a new folder `docs/tutorials/geosciences`,
139
173
together with an `index.md` that describes what these tutorials would be about, and then update `_toc.yml` as below:
140
174
141
175
```yaml
@@ -175,41 +209,75 @@ also be caught when previewing the built documentation. If your documentation
175
209
change does not include code, you only need the napari docs dependencies
176
210
installed.
177
211
178
-
There are two ways you can preview the documentation website, by building
179
-
locally or downloading the GitHub Actions built documentation when you submit
212
+
There are two ways you can preview the documentation website: by building
213
+
locally, or downloading the GitHub Actions built documentation when you submit
180
214
your pull request.
181
215
182
-
To build the documentation locally, run `make docs` from the root of
183
-
the `napari` repository (assuming you've installed the [docs prerequisites](#prerequisites)).
216
+
To build the documentation locally, run `make docs` from the root of your local
217
+
clone of the `napari/docs` repository (assuming you've installed the
218
+
[docs prerequisites](#prerequisites)).
184
219
185
220
```bash
186
221
make docs
187
222
```
188
223
189
-
The rendered HTML will be placed in `napari/docs/_build`. Find `index.html` in this folder and drag it
190
-
into a browser to preview the website with your new document.
224
+
````{note}
225
+
The `make docs` command above assumes your have a local clone of the
226
+
[`napari/napari`](https://github.com/napari/napari) repo at the same level as
227
+
the `napari/docs` clone. If that's not the case, you can specify the location of
228
+
the examples gallery folder by executing
229
+
230
+
```bash
231
+
make docs GALLERY_PATH=<path-to-examples-folder>
232
+
```
233
+
234
+
The `GALLERY_PATH` option must be given relative to the `docs` folder. If your
235
+
folder structure is
236
+
237
+
```
238
+
├── napari-docs
239
+
│ └── docs
240
+
├── napari
241
+
│ ├── binder
242
+
│ ├── examples
243
+
│ ├── napari
244
+
│ ├── napari_builtins
245
+
│ ├── resources
246
+
│ └── tools
247
+
```
248
+
249
+
Then the command would be
250
+
```bash
251
+
make docs GALLERY_PATH=../../napari/examples
252
+
```
253
+
254
+
````
255
+
256
+
The rendered HTML will be placed in `docs/_build`. Find `index.html` in this
257
+
folder and drag it into a browser to preview the website with your new document.
191
258
192
-
Alternatively, When you submit your pull request, napari continuous integration
193
-
includes a GitHub action that builds the documentation and saves the artifact
194
-
for you to download. This is another way to check that your built documentation
195
-
looks as you expect. To download the built documentation, go to your PR, scroll
196
-
down to the continuous integration tests, then:
259
+
Alternatively, when you submit your pull request, the napari docs repository
260
+
continuous integration includes a GitHub action that builds the documentation
261
+
and saves the artifact for you to download. This is another way to check that
262
+
your built documentation looks as you expect. To download the built
263
+
documentation, go to your PR, scroll down to the continuous integration tests,
264
+
then:
197
265
198
-
1. click on 'details' next to 'Build Docs / Build & Upload Artifact (pull_request)'
266
+
1.Click on **Details** next to `Build PR Docs / Build & Upload Artifact (pull_request)`:
Once you have written and previewed your document, it's time to open a pull request to [napari's main repository](https://github.com/napari/napari) and contribute it to our codebase.
280
+
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.
213
281
214
282
If you are simply contributing one file (e.g., a tutorial or how-to page) you
215
283
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
0 commit comments