add (possibly slightly off) source lines to mangled docstrings. #61
Conversation
|
Thanks! How does the new error message look after this?
|
|
same as without numpydoc: |
|
It would be great to have the line number in the |
|
I found out that there were just a couple of empty lines added and other empty lines removed in the parsing which made the line length different . I'm trying to figure that out, so we can get better matching line numbers. |
|
ok I did a rough heuristic for better lines. The main reason I prefer the heuristic is that classes are single documents, and I want to know which method the problem is in. This information gets lost otherwise. My heuristic might be off, but I think it's a net improvement. I ran it over the scikit-learn docs and it didn't break in a horrible way. |
| for i, line in enumerate(lines): | ||
| # go to next non-empty line in old: | ||
| # line.strip("") checks whether the string is all whitespace | ||
| while j < len(lines_old) - 1 and not lines_old[j].strip(" "): |
| @@ -184,6 +183,33 @@ class NumpyCDomain(ManglingDomainBase, CDomain): | |||
| } | |||
|
|
|||
|
|
|||
| def match_items(lines, content_old): | |||
| """Create the right items for lines. | |||
There was a problem hiding this comment.
I found myself digging into the docutils source to figure out what these "right 'items'" are. Can we clear up the docstring of this function a bit, describing what it is doing and why? I see some of that below, but it's not easy to understand without the context of the PR.
There was a problem hiding this comment.
will do. These are really "Best guess".
So the explanation will be "most of the lines are the same after mangling, but we delete and insert some blank lines. This function tries to match the lines as best as possible. Any other changes, like including figures or reformatting references will lead to wrong line numbers." And then I'll explain the scan that I do.
There was a problem hiding this comment.
Actually, this has nothing to do with docutils. The mangle_docstring function changes the lines but not the items. That's pretty much a design error. It should keep track of both.
There was a problem hiding this comment.
I added a really long-winded explanation and a doctest. Better ? ;)
|
@amueller The new docstring is excellent, thank you! |
|
I don't understand the test failure... "cannot import monkey" |
|
No idea! Let me restart that build.
|
|
@amueller Do you mind rebasing? (I'll try to have Stéfan push the green button today, as this patch will be super useful for our students) |
more agressive change to match up new lines with old lines.
adjust expectations in docstring
strip() instead of strip(" ")
added really long explanation and doctest
make lines actually 80 chars long and dont guess
typo
amueller
force-pushed
the
add_source_lines
branch
from
78435bf to
6546f06
Compare
|
@NelleV Done :) |
1 similar comment
|
@NelleV Done :) |
|
They'll be working on matplotlib. I think the first task is going to be documentation changes. We're supposed to have a website, but I don't know where it is yet. |
|
"we"? anyhow, I hope this helps. I've been lobbying for matplotlib documentation changes but didn't find any pots of gold yet :( |
|
We being @stefanv and me, but I just hoped on the project a couple of weeks ago. Stéfan has already run this once during the spring, but I wasn't at Berkeley yet. He knows where the source of the website is, while I am still getting up to speed on pretty much everything. |
|
thanks for the merge @stefanv, hope this helps. |
|
Thanks for the patch!
|
Fixes #52 to some degree.
This adds references to the original source files instead of gigantic output.
However, the numpy mangling might add lines and so the numbers might be slightly off.
I would argue this is already a big improvement though.
This change is