16903, “bradcray”, “chpldoc sphinx errors should be reported using ‘.chpl’ line numbers”, “2021-01-05T18:25:18Z”
Currently, when a chpldoc command fails because sphinx is issuing an error about the comment string not being formatted as expected, it does so in terms of the generated .rst file. This can be confusing because the typical chpldoc user may have no idea about chpldoc’s use of sphinx or underlying .rst files. It would be better if chpldoc reported errors in terms of the user’s .chpl file instead.
For example, running chpldoc on this file, where I’ve commented out a routine that I no longer want in my code base:
/*
proc foo() {
writeln("This is a commented out piece of code, not a chpldoc comment");
}
*/
proc bar() {
writeln("This is procedure bar()");
}
bar();
generates the message:
Running Sphinx v3.2.1
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: [new config] 2 added, 0 changed, 0 removed
reading sources... [ 50%] index
reading sources... [100%] modules/badComment.doc
Warning, treated as error:
/var/folders/[big-tmpdir-name]/source/modules/badComment.doc.rst:25:Definition list ends without a blank line; unexpected unindent.
error: building html output from chpldoc sphinx project
As a user, it’s not clear to me what the .rst file is (and it doesn’t exist anymore for me to inspect it), or what I would need to do to my source file to fix these errors. (In a short program like the one here, it’s pretty obvious that this file isn’t ready for chpldoc, but if this pattern shows up in a much larger code base, it can be challenging to get to the source of the problem.
When I think about what it would take to do this, I wonder whether:
- sphinx has a way of mapping lines back to the original source locations or definitions, similar to
# linedirectives in cpp - we’d have to learn to parse comments to ensure their legality within
chpldocitself if not