Changing @stencil docs to correctly reflect func_or_mode param
#3594
Conversation
|
Thanks for the PR. I think that the intention of the proposed deleted paragraph was to note that there is at present only one option for border handling |
|
Ah, that makes sense, I see that that's also covered in the I've just noticed #3486 hits this section of the docs, so I'll change to use |
yes please, I think that should be fine, the parallel version just wraps and manipulates the serial version so I think the declared kwargs are the same.
If you've any ideas on a way to make that clearer such that it reads in a manner that doesn't make it seem to refer to all the options (which I guess is the motivation for this PR?) then that would be great! Many thanks. |
Codecov Report
@@ Coverage Diff @@
## master #3594 +/- ##
=======================================
Coverage 80.68% 80.68%
=======================================
Files 393 393
Lines 80485 80485
Branches 9164 9164
=======================================
Hits 64942 64942
Misses 14127 14127
Partials 1416 1416 |
|
I've re-added the original paragraph (my bad!) and modified the docs to point to |
AaronCritchley
changed the title
@stencil docs@stencil docs to correctly reflect func_or_mode param
docs/source/user/stencil.rst
Outdated
| -------- | ||
|
|
||
| The optional mode parameter controls how the border of the output array | ||
| The optional func_or_mode parameter controls how the border of the output array |
There was a problem hiding this comment.
func_or_mode should probably have double back ticks around as it looks strange when rendered as it's clearly a parameter to a function (evident from underscores in name).
There was a problem hiding this comment.
Done! (Sorry for the delay)
|
I've reviewed the text that was proposed as text for removal. How about doing the following... Switch the text block to a note, and adjust the wording as follows: .. note::
The stencil decorator may be augmented in the future to provide additional
mechanisms for border handling. At present, only one behaviour is
implemented, ``"constant"`` (see ``func_or_mode`` below for details).What do you think? Does this make the intended clearer? |
Yep, looks great and lots clearer, thanks! |
| @@ -171,10 +172,10 @@ specified neighborhood, **the behavior is undefined.** | |||
|
|
|||
| .. _stencil-mode: | |||
|
|
|||
| ``mode`` | |||
| ``func_or_mode`` | |||
There was a problem hiding this comment.
Title underline needs extending to the same number of chars as the title. Docs are built with warning-as-error so I think this will fail to build.
There was a problem hiding this comment.
@AaronCritchley, I've fixed this in b7d223f.
There was a problem hiding this comment.
Thank you for fixing, sorry for not catching this, I didn't build the docs after my change, lesson learnt 😄
There was a problem hiding this comment.
No problem. Thanks for instigating these changes, the stencil options read better now!
As title.
The existing comment looks inaccurate, the documentation below goes through the options for the
@stencildecorator and there are more than the one option the doc would suggest. 😄Let me know if I've misunderstood / misread though!