Some fixes for the formatting of the documentation #912
Conversation
| @@ -143,9 +143,9 @@ | |||
| def is_any_closer(r, r0, dist=2.5): | |||
| return np.any(r < dist) | |||
|
|
|||
| The first two parameters `r` and `r0` are provided by :class:`Contacts` when it | |||
| The first two parameters ``r`` and ``r0`` are provided by :class:`Contacts` when it | |||
There was a problem hiding this comment.
I started a double backtick rage before realizing that it was not consistent throughout the doc anyway. My reasoning was that r and r0 refer to arguments, therefore to code, and that code is in monospace style.
There was a problem hiding this comment.
I thought single backticks is enough for the monospace style.
There was a problem hiding this comment.
It is in markdown, not in rst. In rst single ticks mean italic.
Le 22 juil. 2016 6:31 PM, Max Linke [email protected] a écrit :In package/MDAnalysis/analysis/contacts.py:
@@ -143,9 +143,9 @@
def is_any_closer(r, r0, dist=2.5):
return np.any(r < dist)-The first two parameters
randr0are provided by :class:Contactswhen it
+The first two parametersrandr0are provided by :class:Contactswhen it
I thought single backticks is enough for the monospace style.
—You are receiving this because you authored the thread.Reply to this email directly, view it on GitHub, or mute the thread.
There was a problem hiding this comment.
Actually, single backticks are mandated in the NumPy doc style for references to variable names (scroll down to 4. Parameters).
|
@jbarnoud - kudos to you for cleaning up the docs. |
|
I reverted the backticks and restored the space before the columns. I also added some more minor fixes. |
| :func:`rmsd` calculates the RMSD between *a* and *b*; for fitting a whole | ||
| trajectory it is more efficient to use :func:`rms_fit_trj`. A complete fit | ||
| of two structures can be done with :func:`alignto`. """ | ||
| MDAnalysis.analysis.rms.rmsd: Calculates the RMSD between *a* and *b*. |
There was a problem hiding this comment.
Does this build as a list, one item per line?
There was a problem hiding this comment.
Are the functions/classes automatically hyperlinked or does one need markup, e.g. :func:alignto?
There was a problem hiding this comment.
It builds as a list, one item per line
There was a problem hiding this comment.
It creates a list indeed. And the links are done automatically. The See also section expect that format (which I do not like much).
Minor missformatting of docstring can cause part of the documentation not to be rendered. This commit fixes some of this formatting issues. In some occurences, it also updates some docstring refering to deprecated methods. The commit also restores the documentation for gromacs trajectory formats. Fixes 855
|
I just rebased against develop and squashed the commits. |
| ``N*(N-1)/2`` numpy 1D array with the distances dist[i,j] between ref | ||
| coordinates i and j at position d[k]. Loop through d: | ||
|
|
||
| .. code-block:: python |
There was a problem hiding this comment.
Out of curiosity, do we need to markup code as python? I think sphinx's default is python.
There was a problem hiding this comment.
Not sure that specific change was required. It does not hurt, though.
|
Looks ready to me. Can I merge? |
|
It is good for me. |
|
Many thanks @jbarnoud ! |
Some fixes for the formatting of the documentation
Fixes #855 among other things
Changes made in this Pull Request:
The doc rendering is broken at several places because the markup format is not followed in docstrings. Hereby, I fix some of this formatting issues to fix the rendering of some doc pages.
PR Checklist
Tests?Not applicableCHANGELOG updated?Nothing new