[REVIEW] Fixing Python Documentation Errors and Warnings #3428
Conversation
mdemoret-nv
added
bug
|
@gpucibot merge |
| faster distances calculations | ||
| The query algorithm to use. Valid options are: | ||
|
|
||
| - ``'brute'``: for brute-force, slow but produces exact results |
There was a problem hiding this comment.
why are the double backticks needed? should all string args be in double backticks?
There was a problem hiding this comment.
Single and double backticks are shown differently in the documentation. Here is what single backticks look like (italicized, variable spaced):
And this is what double backticks look like (bold, monospaced, red):
(Depending on where you are viewing the documentation from, there might be slight differences in color, size, etc.)
Generally in Sphinx, you want to use single backticks when you are referring to some other object that exists (i.e. named argument, class, function, etc.). And you want to use double backticks for inline code (which is different than Markdown which everyone is familiar with).
For this particular example, I like to use the double backticks around string literals because: 1) it makes them stand out here in the list, 2) string literals aren't referencing any other object and 3) emphasizes that this code can be copy/pasted if needed.
This really only touches the surface since single backticks are technically "interpreted code" which is domain specific and can be modified with labels. For example, you can cross-reference links in the code by using :ref:`some-other-link` (The :ref: part being a label. See here for the long list of available labels)
| @@ -214,7 +216,7 @@ class SVC(SVMBase, ClassifierMixin): | |||
| coef_ : float, shape (1, n_cols) | |||
| Only available for linear kernels. It is the normal of the | |||
| hyperplane. | |||
| coef_ = sum_k=1..n_support dual_coef_[k] * support_vectors[k,:] | |||
| ``coef_ = sum_k=1..n_support dual_coef_[k] * support_vectors[k,:]`` | |||
There was a problem hiding this comment.
ah, so it's double backticks here too -- should every code block in a comment be doubled like that?
There was a problem hiding this comment.
So there were two issues here. If you use a trailing underscore in reST, that means you want to link to an object. So above, coef_ means link to the object named coef. Since no label has been created with the name coef, it generated the following error:
WARNING: Unknown target name: "coef"
Since this section of text was in fact inline code, surrounding it in double backticks correctly displays it as code and also removes the link. So two birds, one stone.
Codecov Report
@@ Coverage Diff @@
## branch-0.18 #3428 +/- ##
===============================================
- Coverage 71.48% 71.40% -0.09%
===============================================
Files 207 210 +3
Lines 16748 16839 +91
===============================================
+ Hits 11973 12024 +51
- Misses 4775 4815 +40
Continue to review full report at Codecov.
|
Closes #3268
General cleanup of sphinx documentation to eliminate all warnings and fix issue #3268. Main change was using
autofunction::instead ofautomethod::(which is designed for class methods)