Validates the doc string in a snippet of documentation `text` from file `name` Parameters ---------- text : str Docstring text name : str File name for which the doc string is to be validated dots : bool Whether to print a dot symbol for each chec
(text, name, dots=True)
| 431 | |
| 432 | |
| 433 | def validate_rst_syntax(text, name, dots=True): |
| 434 | """ |
| 435 | Validates the doc string in a snippet of documentation |
| 436 | `text` from file `name` |
| 437 | Parameters |
| 438 | ---------- |
| 439 | text : str |
| 440 | Docstring text |
| 441 | name : str |
| 442 | File name for which the doc string is to be validated |
| 443 | dots : bool |
| 444 | Whether to print a dot symbol for each check |
| 445 | Returns |
| 446 | ------- |
| 447 | (bool, str) |
| 448 | """ |
| 449 | if text is None: |
| 450 | if dots: |
| 451 | output_dot('E') |
| 452 | return False, "ERROR: %s: no documentation" % (name,) |
| 453 | |
| 454 | ok_unknown_items = set([ |
| 455 | 'mod', 'doc', 'currentmodule', 'autosummary', 'data', 'attr', |
| 456 | 'obj', 'versionadded', 'versionchanged', 'module', 'class', |
| 457 | 'ref', 'func', 'toctree', 'moduleauthor', 'term', 'c:member', |
| 458 | 'sectionauthor', 'codeauthor', 'eq', 'doi', 'DOI', 'arXiv', 'arxiv' |
| 459 | ]) |
| 460 | |
| 461 | # Run through docutils |
| 462 | error_stream = io.StringIO() |
| 463 | |
| 464 | def resolve(name, is_label=False): |
| 465 | return ("http://foo", name) |
| 466 | |
| 467 | token = '<RST-VALIDATE-SYNTAX-CHECK>' |
| 468 | |
| 469 | docutils.core.publish_doctree( |
| 470 | text, token, |
| 471 | settings_overrides = dict(halt_level=5, |
| 472 | traceback=True, |
| 473 | default_reference_context='title-reference', |
| 474 | default_role='emphasis', |
| 475 | link_base='', |
| 476 | resolve_name=resolve, |
| 477 | stylesheet_path='', |
| 478 | raw_enabled=0, |
| 479 | file_insertion_enabled=0, |
| 480 | warning_stream=error_stream)) |
| 481 | |
| 482 | # Print errors, disregarding unimportant ones |
| 483 | error_msg = error_stream.getvalue() |
| 484 | errors = error_msg.split(token) |
| 485 | success = True |
| 486 | output = "" |
| 487 | |
| 488 | for error in errors: |
| 489 | lines = error.splitlines() |
| 490 | if not lines: |
no test coverage detected