Error codes missing from ReadTheDocs as of 4.0.0

[lordmauve]

On ReadTheDocs, the current error codes page has a blank Grouping heading.

For the 3.0.0 release docs, this is where the table of error codes would be printed.

[peterjc]

I found this issue while trying to find documentation on new code D417: Missing arguments in the function docstring, added in 6de6d93 as part of #357 (initial GoogleDoc convention).

I note that http://www.pydocstyle.org/en/4.0.0/error_codes.html#default-conventions is also missing documentation of the new google convention.

[peterjc]

There must have been a problem with the included file docs/snippets/error_code_table.rst (which is not under version control), it is meant to have been generated via docs/conf.py

[lordmauve]

Ew, that sounds like a hack. Importing conf.py isn't supposed to have side-effects. Maybe ReadTheDocs is now caching the contents of conf.py?

[peterjc]

Importing conf.py is the accepted way to run sphinx-apidoc on RTD, and probably the only way to have any dynamic content on RTD - so I can see why that would be done.

Looking at the RTD build logs might be instructive...

[lordmauve]

I checked the log of a recent build and it doesn't look like they use caching - indeed they append extra build config to each conf.py.

[lordmauve]

Oh, here's the issue:

WARNING: snippets/error_code_table.rst:1: (ERROR/3) Malformed table.

+------+-----------------------------------------------------------------------+
|                                                                              |
|                            **Missing Docstrings**                            |
|                                                                              |
+------+-----------------------------------------------------------------------+
| D100 | Missing docstring in public module                                    |
+------+-----------------------------------------------------------------------+
| D101 | Missing docstring in public class                                     |
+------+-----------------------------------------------------------------------+
| D102 | Missing docstring in public method                                    |
+------+-----------------------------------------------------------------------+
| D103 | Missing docstring in public function                                  |
+------+-----------------------------------------------------------------------+
| D104 | Missing docstring in public package                                   |
+------+-----------------------------------------------------------------------+
| D105 | Missing docstring in magic method                                     |
+------+-----------------------------------------------------------------------+
| D106 | Missing docstring in public nested class                              |
+------+-----------------------------------------------------------------------+
| D107 | Missing docstring in __init__                                         |
+------+-----------------------------------------------------------------------+
|                                                                              |
|                            **Whitespace Issues**                             |
|                                                                              |
+------+-----------------------------------------------------------------------+
| D200 | One-line docstring should fit on one line with quotes                 |
+------+-----------------------------------------------------------------------+
| D201 | No blank lines allowed before function docstring                      |
+------+-----------------------------------------------------------------------+
| D202 | No blank lines allowed after function docstring                       |
+------+-----------------------------------------------------------------------+
| D203 | 1 blank line required before class docstring                          |
+------+-----------------------------------------------------------------------+
| D204 | 1 blank line required after class docstring                           |
+------+-----------------------------------------------------------------------+
| D205 | 1 blank line required between summary line and description            |
+------+-----------------------------------------------------------------------+
| D206 | Docstring should be indented with spaces, not tabs                    |
+------+-----------------------------------------------------------------------+
| D207 | Docstring is under-indented                                           |
+------+-----------------------------------------------------------------------+
| D208 | Docstring is over-indented                                            |
+------+-----------------------------------------------------------------------+
| D209 | Multi-line docstring closing quotes should be on a separate line      |
+------+-----------------------------------------------------------------------+
| D210 | No whitespaces allowed surrounding docstring text                     |
+------+-----------------------------------------------------------------------+
| D211 | No blank lines allowed before class docstring                         |
+------+-----------------------------------------------------------------------+
| D212 | Multi-line docstring summary should start at the first line           |
+------+-----------------------------------------------------------------------+
| D213 | Multi-line docstring summary should start at the second line          |
+------+-----------------------------------------------------------------------+
| D214 | Section is over-indented                                              |
+------+-----------------------------------------------------------------------+
| D215 | Section underline is over-indented                                    |
+------+-----------------------------------------------------------------------+
|                                                                              |
|                              **Quotes Issues**                               |
|                                                                              |
+------+-----------------------------------------------------------------------+
| D300 | Use """triple double quotes"""                                        |
+------+-----------------------------------------------------------------------+
| D301 | Use r""" if any backslashes in a docstring                            |
+------+-----------------------------------------------------------------------+
| D302 | Use u""" for Unicode docstrings                                       |
+------+-----------------------------------------------------------------------+
|                                                                              |
|                         **Docstring Content Issues**                         |
|                                                                              |
+------+-----------------------------------------------------------------------+
| D400 | First line should end with a period                                   |
+------+-----------------------------------------------------------------------+
| D401 | First line should be in imperative mood                               |
+------+-----------------------------------------------------------------------+
| D401 | First line should be in imperative mood; try rephrasing               |
+------+-----------------------------------------------------------------------+
| D402 | First line should not be the function's "signature"                   |
+------+-----------------------------------------------------------------------+
| D403 | First word of the first line should be properly capitalized           |
+------+-----------------------------------------------------------------------+
| D404 | First word of the docstring should not be `This`                      |
+------+-----------------------------------------------------------------------+
| D405 | Section name should be properly capitalized                           |
+------+-----------------------------------------------------------------------+
| D406 | Section name should end with a newline                                |
+------+-----------------------------------------------------------------------+
| D407 | Missing dashed underline after section                                |
+------+-----------------------------------------------------------------------+
| D408 | Section underline should be in the line following the section's name  |
+------+-----------------------------------------------------------------------+
| D409 | Section underline should match the length of its name                 |
+------+-----------------------------------------------------------------------+
| D410 | Missing blank line after section                                      |
+------+-----------------------------------------------------------------------+
| D411 | Missing blank line before section                                     |
+------+-----------------------------------------------------------------------+
| D412 | No blank lines allowed between a section header and its content       |
+------+-----------------------------------------------------------------------+
| D413 | Missing blank line after last section                                 |
+------+-----------------------------------------------------------------------+
| D414 | Section has no content                                                |
+------+-----------------------------------------------------------------------+
| D415 | First line should end with a period, question mark, or exclamation point|
+------+-----------------------------------------------------------------------+
| D416 | Section name should end with a semicolon                              |
+------+-----------------------------------------------------------------------+
| D417 | Missing arguments in the function docstring                           |
+------+-----------------------------------------------------------------------+

[peterjc]

Looks like D415 broke the table - if so there are less fragile RST table layouts without the vertical bars which would work better here.

[peterjc]

Self-contained snippet for testing:

$ python -c "from pydocstyle.violations import ErrorRegistry; print(ErrorRegistry.to_rst())" > error_code_table.rst

$ pip install restructuredtext-lint
$ restructuredtext-lint error_code_table.rst
ERROR error_code_table.rst:1 Malformed table.

[lordmauve]

@Nurdok Could you tag a 4.0.0.post1 release in master? Simply tagging will update ReadTheDocs stable (no need to upload a new package to PyPI).