Typically, all of our function arguments are documented in prose, though there's some variation on whether references to the variable name are enclosed in angled brackets.
We typically refer to argument names by either a simple plaintext name, or a plaintext name surrounded with angled brackets. Sphinx/docutils/rst use "roles" to make official (and semantic) references to things, so we could have something like :arg:\sum`` if we wanted to, and then present them however we liked in HTML and plaintext. Sphinx won't give us any special formatting for the plaintext or angled-bracket references without changing the markup to something like the above. How important is having these marked up to us? What do we want them to look like in the plaintext?
My own thoughts on the value of 1. are clouded by how much work it would be, but I don't think that should necessarily stop us from being idealistic enough to say, you know, all of the docs should reach that target by some future version number, and having an unofficial policy in the interim that any time you muck around in a doc, you fix it, in which case I could do a subset as a reference to start us off.
The "easy" answer to 2. is to strip out all of the angled brackets and do nothing special for any of the arg references. It isn't something we can just run a batch replace on, because things other than arg references use the angled brackets to imply a variable of some sort, or for other organizational purposes. That said, if we want all args to be marked up in the HTML and plaintext, I'll do my best to make it happen while I work on other issues.
Typically, all of our function arguments are documented in prose, though there's some variation on whether references to the variable name are enclosed in angled brackets.
There are two questions here:
:arg:\sum`` if we wanted to, and then present them however we liked in HTML and plaintext. Sphinx won't give us any special formatting for the plaintext or angled-bracket references without changing the markup to something like the above. How important is having these marked up to us? What do we want them to look like in the plaintext?My own thoughts on the value of 1. are clouded by how much work it would be, but I don't think that should necessarily stop us from being idealistic enough to say, you know, all of the docs should reach that target by some future version number, and having an unofficial policy in the interim that any time you muck around in a doc, you fix it, in which case I could do a subset as a reference to start us off.
The "easy" answer to 2. is to strip out all of the angled brackets and do nothing special for any of the arg references. It isn't something we can just run a batch replace on, because things other than arg references use the angled brackets to imply a variable of some sort, or for other organizational purposes. That said, if we want all args to be marked up in the HTML and plaintext, I'll do my best to make it happen while I work on other issues.