Docbuild issues are hard to see and understand

[Andrey Novoseltsev]

Hello,

I just fixed a couple of format problems in documentation (using git in case it matters) and had two problems with the way docbuid works:

1. There is no message about warning in the end of the output. As the process takes a while, I am not watching what's going on and when I come back to the terminal I see a lot of statistics but have to scroll up and search for warnings/errors. Would be way better if they were summarized in the end as it is done with doctests.

2. Line numbers are completely screwed up - I could not figure out what is wrong with 4 and 14, because they both were in the second thousand far away from each other. I ended up looking through the whole file.

Is this something known or does anybody know how to fix it? I am pretty sure that line numbers used to be correct.

Thank you!
Andrey

[Eric Gourgoulhon]

Hi,

I totally subscribe to your point 2: the line numbers provided with warnings during the documentation built do not correspond to actual line numbers in the source files. I do not know the meaning of these line numbers. Does anybody have some hint about this ?

Best wishes,

Eric.

[Volker Braun]

I think the line numbers are relative to the beginng of the docstring, not the whole file. It would be nice if Sphinx would print some context...

[Travis Scrimshaw]

Hey Andrey,

I just fixed a couple of format problems in documentation (using git in case it matters) and had two problems with the way docbuid works:

1. There is no message about warning in the end of the output. As the process takes a while, I am not watching what's going on and when I come back to the terminal I see a lot of statistics but have to scroll up and search for warnings/errors. Would be way better if they were summarized in the end as it is done with doctests.

In care you are unaware, I would recommend doing a more narrow docbuild with "reference/subsection" where subsection is for example combinat or algebras. Also on the next time you're rebuilding the doc, it should only print about what files were changed, so it shouldn't be too far to scroll. IDK, I guess what I'm saying is I've never really thought that this was an issue.

 

2. Line numbers are completely screwed up - I could not figure out what is wrong with 4 and 14, because they both were in the second thousand far away from each other. I ended up looking through the whole file.

Is this something known or does anybody know how to fix it? I am pretty sure that line numbers used to be correct.

   As Volker stated, it's relative to the start of the docstring, but it would be nice to have some absolute positioning in the file. IMO the best method to figure out where a docstring problem is to look through the output as they tend to make a portion be clearly misformatted.

Best,

Travis

[Andrey Novoseltsev]

Hi Travis,

On Sunday, 29 September 2013 20:12:48 UTC+1, Travis Scrimshaw wrote:

In care you are unaware, I would recommend doing a more narrow docbuild with "reference/subsection" where subsection is for example combinat or algebras. Also on the next time you're rebuilding the doc, it should only print about what files were changed, so it shouldn't be too far to scroll. IDK, I guess what I'm saying is I've never really thought that this was an issue.

I was aware, but forgot, given that it does not take too much time compared say to long testing a particular section. I'd still prefer an option to have only errors/warnings reported or repeated/summarized in the very end, even if it is just "There were warnings".

   As Volker stated, it's relative to the start of the docstring, but it would be nice to have some absolute positioning in the file. IMO the best method to figure out where a docstring problem is to look through the output as they tend to make a portion be clearly misformatted.

There is a big difference in time spent looking at line 1234 where the error was detected and looking at a compiled documentation with a hundred methods. In my case errors were not obvious to scrolling through: one was wrong indentation for seealso which made the link appear not on a yellow background, which is not particularly visible on my laptop screen anyway, unless I look at it at a particular angle. One can of course look at what the branch is changing and then search for those methods (which, of course, tend to be in a different order). But no matter what - reading the line number is MUCH faster than manually trying to figure it out!

So if someone can translate line numbers to something meaningful or at least show a line of context, please implement it!

Thank you,
Andrey
 

[Volker Braun]

I agree that the current state is bad. Also, the sphinx error frequently points you at the docstring of the wrong class/method in the file so you need to hunt through the whole file content to find where it hurts. We should definitely improve on that. Can somebody open at ticket?

[Andrey Novoseltsev]

Will do!

[Andrey Novoseltsev]

http://trac.sagemath.org/ticket/15242