Document how to contribute a gallery example. #4857
Conversation
CONTRIBUTING.txt
Outdated
| ~~~~~~~ | ||
|
|
||
| If you are contributing an example to the | ||
| `gallery <https://scikit-image.org/docs/dev/auto_examples/>`_ (or editing an |
There was a problem hiding this comment.
Should this be an internal link (ref?) instead? There is another link to a https://scikit-image.org/ page elsewhere (line 83), so I left it this way...
There was a problem hiding this comment.
I think a ref is better, good suggestion! Anyone else @scikit-image/core got an opinion?
There was a problem hiding this comment.
Done as part of bdfbbd2.
Then I thought I might as well change the other https://scikit-image.org/ link: 0fd5eb9.
Also, from https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html, it seems that the link text at
Line 256 in 7e4840b
is unnecessary, 'Coordinate conventions' being the title following the
numpy-images-coordinate-conventions label (file doc/source/user_guide/numpy_images.rst).
CONTRIBUTING.txt
Outdated
| existing one), write in | ||
| `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_. | ||
| Indeed, the gallery is a | ||
| `Sphinx-Gallery <https://sphinx-gallery.github.io/stable/index.html>`_ one. |
There was a problem hiding this comment.
"one" might be unnecessary
There was a problem hiding this comment.
The gallery is created using Sphinx-Gallery <https://sphinx-gallery.github.io>_. Refer to that page for complete instructions on syntax and usage.
There was a problem hiding this comment.
Thanks for this better wording! Included in bdfbbd2. I don't love my first sentence in the new [sub * (n + 1)]section ('The above-mentioned command includes the installation of Sphinx-Gallery.') but I thought repeating
pip install -r requirements/docs.txtwouldn't be great either...
CONTRIBUTING.txt
Outdated
| existing one), write in | ||
| `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_. | ||
| Indeed, the gallery is a | ||
| `Sphinx-Gallery <https://sphinx-gallery.github.io/stable/index.html>`_ one. |
There was a problem hiding this comment.
The gallery is created using Sphinx-Gallery <https://sphinx-gallery.github.io>_. Refer to that page for complete instructions on syntax and usage.
CONTRIBUTING.txt
Outdated
| Indeed, the gallery is a | ||
| `Sphinx-Gallery <https://sphinx-gallery.github.io/stable/index.html>`_ one. | ||
|
|
||
| Refer to the above to build (all) the docs, and check how your edits render at |
There was a problem hiding this comment.
Maybe mention the browser here, otherwise newcomers might not know how to check.
There was a problem hiding this comment.
Good point, realized that when replying: #4851 (comment)
Done bdfbbd2.
CONTRIBUTING.txt
Outdated
| ``scikit-image/doc/build/html/auto_examples/`` (navigate to the file you have | ||
| added or changed). | ||
|
|
||
| When adding an example, visit also |
There was a problem hiding this comment.
I find there is a slight difference in meanings, but I'm not sure: I wrote 'visit also index.html' because the contributor was just told to visit another page (visit A, visit also B); 'also visit' sounds like the previous instruction would entail an action different from visiting a web page (e.g., run make html, also visit the resulting web pages).
alexdesiqueira
added
the
📄 type: Documentation
|
Ready for the next round of reviews, thanks! |
CONTRIBUTING.txt
Outdated
| @@ -222,13 +221,13 @@ Guidelines | |||
| * All code should have tests (see `test coverage`_ below for more details). | |||
| * All code should be documented, to the same | |||
| `standard <https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`_ as NumPy and SciPy. | |||
| * For new functionality, always add an example to the gallery. | |||
| * For new functionality, always add an example to the gallery (see | |||
| sphinx_gallery_ below for more details). | |||
There was a problem hiding this comment.
| sphinx_gallery_ below for more details). | |
| :ref:`_sphinx_gallery` below for more details). |
?
There was a problem hiding this comment.
It should be
:ref:`sphinx_gallery`then. I thought I would try the 'first method' (according to https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#explicit-links) but I'm happy to use :ref: everywhere (might be more standard, reading https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html).
Co-authored-by: Juan Nunez-Iglesias <[email protected]>
Co-authored-by: Juan Nunez-Iglesias <[email protected]>
|
@jni thanks for your final review! I have included your suggestions. |
|
The Appveyor failure seems to be independent of this PR, so I'm merging. Thank you @mkcor! |
Description
We identified the need for these instructions while reviewing and reading PR reviews.
Checklist
./doc/examples(new features only)./benchmarks, if your changes aren't covered by anexisting benchmark
For reviewers
later.
__init__.py.doc/release/release_dev.rst.