Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Implement --enable and --disable. #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 31 commits into from
May 13, 2022
Merged

Implement --enable and --disable. #27

merged 31 commits into from
May 13, 2022

Conversation

JulienPalard
Copy link
Collaborator

@JulienPalard JulienPalard commented May 1, 2022

Just before being offline for a week, I tried myself at implementing --enable to help sphinx-doc/sphinx#10389 (comment).

I added a --list option:

$ python sphinxlint.py --enable all --list
- block-bad-dedent: Check for dedent not being enough in code blocks.
- carriage-return: Check for carriage return in lines.
- default-role: Search for default roles (but they are allowed in many projects).
- directives-missing-column: Search for directive wrongly typed as comments, like: .. versionchanged 3.6.
- directives-using-three-dots: Search for directives with three dots instead of two.
- horizontal-tab: Check for horizontal tabs in lines.
- hyperlinks-missing-space-before-less-than: Search for hyperlinks missing a space, like: `Link text<https://example.com>`.
- hyperlinks-missing-underscore-after-closing-backtick: Search for hyperlinks missing underscore after their closing backtick.
- inline-literal-glued-on-the-right: Search for inline literals glued to plural, like ``items``s.
- leaked-markup: Check HTML files for leaked reST markup; this only works if
- line-too-long: Check for line length; this checker is not run by default.
- newline-at-end-of-file: Check if the last line ends with a newline, like any other lines.
- python-syntax: Search invalid syntax in Python examples.
- roles-glued-to-the-right: Search for roles glued to plurals like: :exc:`Exception`s.
- roles-missing-column-before-backtick: Search for roles missing a column, like: :issue`123`.
- roles-missing-last-backtick: Search for roles missing their closing backticks, like :fct:`foo.
- roles-missing-leading-space: Search for spaces missing before roles, like the:fct:`sum`.
- roles-preceded-with-backtick: Search for roles preceded by a backtick, like `:fct:`sum`.
- roles-with-double-backtick: Search for roles with double backticks like: :fct:``sum``.
- roles-without-backticks: Search roles without backticks like :func:pdb.main.
- trailing-whitespace: Check for trailing whitespaces at end of lines.
- triple-backticks: Check for triple backticks, like ```Point``` (but it's a valid syntax).

It's usefull to experiment with --enable and --disable:

$ python sphinxlint.py --disable all --enable trailing-whitespace,carriage-return --enable newline-at-end-of-file --list
- carriage-return: Check for carriage return in lines.
- newline-at-end-of-file: Check if the last line ends with a newline, like any other lines.
- trailing-whitespace: Check for trailing whitespaces at end of lines.

To make it usefull I had to split many functions, which has an impact on performance, but neglictible compared to the usefullness of being able to enable/disable specific checks. On my laptop running pytest goes from 1.460s to 1.565s (7% slower).

@JulienPalard JulienPalard force-pushed the mdk-enable-disable branch from 6fde792 to 9f575a8 Compare May 1, 2022 16:06
@JulienPalard JulienPalard force-pushed the mdk-enable-disable branch from 702bc1d to 8db6ac9 Compare May 7, 2022 21:16
@JulienPalard
Copy link
Collaborator Author

JulienPalard commented May 7, 2022

Added some tests playing with --list, --enable and --disable.

It does not break our known users (cpython, pandas, sympy, django-oauth-toolkit).

But I'll gladly take a review about test names, as they won't be easy to change if people start using them in --enable and --disable. I tried to add some consistency to the names by grouping them by the kind of syntax they're checking, like directives-*, hyperlinks-*, roles-*...

@JulienPalard
Copy link
Collaborator Author

(@jean-abou-samra, @hugovk, @ezio-melotti, @matilda-me pinging you as contributors to this repo, if you have time to review)

@JulienPalard
Copy link
Collaborator Author

Thanks @jean-abou-samra! Fixed your suggestions.

@jeanas
Copy link
Contributor

jeanas commented May 7, 2022

Thanks for doing this! I did a quick review and didn't find any issues standing out, even though it's been some time since I tinkered with this script.

Copy link
Collaborator

@ezio-melotti ezio-melotti left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left a few comments, mainly about some implementation details and the names of the checkers.

Regarding the names, the following things should be improved:

  • name length (hyperlinks-missing-underscore-after-closing-backtick)
  • consistency (roles-without-backticks, directives-missing-colon, missing-space-after-roles)
  • singular vs plural (some checker use literal or line, others use roles or directives)

(Note that not all my suggestions are consistent, it's a bit tricky to compare the names from the GitHub review UI.)

Once the names are released, it will be difficult to change them, so they must be chosen wisely :)

I would also suggest to check other linters both for their cmd line api, and for checker names:

Copy link
Collaborator

@ezio-melotti ezio-melotti left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few minor nits and some suggestions that are somewhat unrelated to --enable/--disable -- let me know if you want separate issues/PRs for those.

@JulienPalard
Copy link
Collaborator Author

JulienPalard commented May 10, 2022

Thanks a lot for the reviews!

I took the time to rephrase the checkers according to ezio propositions and for consistency, removed all unneeded plurals (as pylint does) ... :

22 checkers selected:
- backtick-before-role: Search for roles preceded by a backtick.
- bad-dedent: Check for mis-alignment in indentation in code blocks.
- carriage-return: Check for carriage returns (\r) in lines.
- default-role: Search for default roles (but they are allowed in many projects).
- directive-missing-colons: Search for directive wrongly typed as comments.
- directive-with-three-dots: Search for directives with three dots instead of two.
- horizontal-tab: Check for horizontal tabs (\t) in lines.
- leaked-markup: Check HTML files for leaked reST markup.
- line-too-long: Check for line length; this checker is not run by default.
- missing-backtick-after-role: Search for roles missing their closing backticks.
- missing-colon-in-role: Search for roles missing a colon.
- missing-final-newline: Check if the last line ends with a newline, like any other lines.
- missing-space-after-literal: Search for inline literals immediately followed by a character.
- missing-space-after-role: Search for roles immediately followed by a character.
- missing-space-before-role: Search for spaces missing before roles.
- missing-space-in-hyperlink: Search for hyperlinks missing a space.
- missing-underscore-after-hyperlink: Search for hyperlinks missing underscore after their closing backtick.
- python-syntax: Search invalid syntax in Python examples.
- role-with-double-backtick: Search for roles with double backticks.
- role-without-backticks: Search roles without backticks.
- trailing-whitespace: Check for trailing whitespaces at end of lines.
- triple-backtick: Check for triple backticks, like ```Point``` (but it's a valid syntax).

(Use `--list --verbose` to know more about each check)

And :

$ python sphinxlint.py --list --verbose

22 checkers selected:
- backtick-before-role: Search for roles preceded by a backtick.

    Bad: `:fct:`sum`
    Good: :fct:`sum`
    
- bad-dedent: Check for mis-alignment in indentation in code blocks.

    |A 5 lines block::
    |
    |    Hello!
    |
    | Looks like another block::
    |
    |    But in fact it's not due to the leading space.
    
- carriage-return: Check for carriage returns (\r) in lines.
- default-role: Search for default roles (but they are allowed in many projects).

    Bad:  `print`
    Good: ``print``
    
- directive-missing-colons: Search for directive wrongly typed as comments.

    Bad:  .. versionchanged 3.6.
    Good: .. versionchanged:: 3.6
    
- directive-with-three-dots: Search for directives with three dots instead of two.

    Bad:  ... versionchanged:: 3.6
    Good:  .. versionchanged:: 3.6
    
- horizontal-tab: Check for horizontal tabs (\t) in lines.
- leaked-markup: Check HTML files for leaked reST markup.

    This only works if the HTML files have been built.
    
- line-too-long: Check for line length; this checker is not run by default.
- missing-backtick-after-role: Search for roles missing their closing backticks.

    Bad:  :fct:`foo
    Good: :fct:`foo`
    
- missing-colon-in-role: Search for roles missing a colon.

    Bad:  :issue`123`
    Good: :issue:`123`
    
- missing-final-newline: Check if the last line ends with a newline, like any other lines.
- missing-space-after-literal: Search for inline literals immediately followed by a character.

    Bad:  ``items``s
    Good: ``items``\ s
    
- missing-space-after-role: Search for roles immediately followed by a character.

    Bad:  :exc:`Exception`s.
    Good: :exc:`Exceptions`\ s
    
- missing-space-before-role: Search for spaces missing before roles.

    Bad:  the:fct:`sum`
    Good: the :fct:`sum`
    
- missing-space-in-hyperlink: Search for hyperlinks missing a space.

    Bad:  `Link text<https://example.com>_`
    Good: `Link text <https://example.com>_`
    
- missing-underscore-after-hyperlink: Search for hyperlinks missing underscore after their closing backtick.

    Bad:  `Link text <https://example.com>`
    Good: `Link text <https://example.com>`_
    
- python-syntax: Search invalid syntax in Python examples.
- role-with-double-backtick: Search for roles with double backticks.

    Bad:  :fct:``sum``
    Good: :fct:`sum`
    
- role-without-backticks: Search roles without backticks.

    Bad:  :func:pdb.main
    Good: :func:`pdb.main`
    
- trailing-whitespace: Check for trailing whitespaces at end of lines.
- triple-backtick: Check for triple backticks, like ```Point``` (but it's a valid syntax).

    Bad: ```Point```
    Good: ``Point``

    In reality, triple backticks are valid: ```foo``` gets
    rendered as `foo`, it's at least used by Sphinx to document rst
    syntax, but it's really uncommon.

@JulienPalard
Copy link
Collaborator Author

Should role-without-backticks be role-without-backtick?

@hugovk
Copy link
Collaborator

hugovk commented May 10, 2022

I think plurals for backtick (but not role) in:

  • role-with-double-backticks
  • role-without-backticks
  • triple-backticks

Because each instance of these errors concerns multiple backticks.

@JulienPalard
Copy link
Collaborator Author

Done:

$ python sphinxlint.py --list --enable all | grep backticks
- missing-backtick-after-role: Search for roles missing their closing backticks.
- role-with-double-backticks: Search for roles with double backticks.
- role-without-backticks: Search roles without backticks.
- triple-backticks: Check for triple backticks, like ```Point``` (but it's a valid syntax).

@JulienPalard
Copy link
Collaborator Author

@ezio-melotti do you think we can merge and release as is, to unlock python/cpython#92290?

Copy link
Collaborator

@ezio-melotti ezio-melotti left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a few minor nits, but otherwise it looks good.

JulienPalard and others added 4 commits May 13, 2022 07:33
Co-authored-by: Ezio Melotti <[email protected]>
Co-authored-by: Ezio Melotti <[email protected]>
Co-authored-by: Ezio Melotti <[email protected]>
Co-authored-by: Ezio Melotti <[email protected]>
@JulienPalard JulienPalard merged commit c0a20d1 into main May 13, 2022
@JulienPalard JulienPalard deleted the mdk-enable-disable branch May 13, 2022 06:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants