Please rename this tool

[gvanrossum]

Tools should not be named after style guide PEPs. A style guide is a document written for humans, and has lots of subtlety. Issues caused by the rigidity or simplicity of the tool end up causing pointless discussion about the letter of the PEP, as if it was a law, which was never the intention of the PEP. If you want to write a tool that checks style, please give it some clever name, don't name it after a PEP, so it's clear that whenever humans don't like what the tool says, it is a tool issue, not an issue with the PEP (which is merely intended to guide humans, not to require them to follow it every time).

[keleshev]

Thanks for speaking out about this. We'll change the name of the command-line tool, of the repository, and of the PyPI package. However, if you don't mind, we'll keep the old ones working for backwards-compatibility.

[gvanrossum]

Thanks for being flexible! FWIW I am happy that this tool exists -- it's just the name I object to. :-)

[Nurdok]

This might be a good place to discuss the new tool name!

I checked PyPI for the following names and they are available:

• pydoc
• doclint
• checkdoc
• docstring-lint

I personally lean towards doclint, but please share your ideas and thoughts about this.

[gvanrossum]

How about pydoclint? A bit long but clear on the scope, since it's primarily a command-line utility -- and it follows the pattern of pylint and pytest.

[sigmavirus24]

• pydoclint sounds like something that will lint your documentation, not docstrings.
• pydoc can't be used because that's something Python installs (e.g., pydoc optparse brings up the documentation for optparse)
• pydocstrings would be my vote. Again, long but (IMO) more explicit than the other options provided other than docstring-lint.

[jirikuncar]

Although my contribution to the package was minimal I would like to add my thoughts too:

• pypep257lint - it might be against the intention of this issue;
• pylint257 - it still refers to PEP257 😉;
• pydoclint - it is my personal favorite;
• pydust, pyfluff - just some wild ideas ...

[sigmavirus24]

On January 5, 2016 11:47:58 AM CST, Jiri Kuncar notifications@github.com wrote:

Although my contribution to the package was minimal I would like to add
my thoughts too:

• pypep257lint - it might be against the intention of this issue;

Right. I think Guido wants us to avoid pep in the name altogether.

• pylint257 - it still refers to PEP257 😉;

But is very tired to the name PyLint which we should avoid

• pydoclint - it is my personal favorite;

I still think this is to vague but I'm not against it.

• pydust, pyfluff - just some wild ideas ...

---

Reply to this email directly or view it on GitHub:
#172 (comment)

Sent from my Android device with K-9 Mail. Please excuse my brevity.

[Nurdok]

With @keleshev's approval and after speaking with @sigmavirus24, it is decided that the new tool's repository will reside under the PyCQA (Python Code Quality Authority). We'll be in good company with pep8, pylint, flake8, etc.

After we choose a name, I'll update the README here to redirect folks to the new repo and work with @sigmavirus24 on the relocation.

---

Regarding the name - it seems to my that while pydoclint is a little bit vague (regarding documentation in general as opposed to specifically docstrings), pydocstrings is vague about what it does about docstrings, which seems more confusing to me.

[jayvdb]

@gvanrossum , are you opposed to this package including a 257 suffix. IMO it should include 257, as it does intend to implement pep257 as best as software and time/energy of developers permits.

I feel pydoclint has an incorrect scope. pydoc is already tightly coupled with pep 258 . pep 258 explicitly allows different syntax/style/etc and non-English language with __docformat__. I would strongly support an increased scope of this package which included parsing __docformat__ and reacting accordingly, such as disabling English specific checks when a non-English language is indicated, and doing rst syntax checking if the __docformat__ indicates the docstring format is rst.

As they are coming under one umbrella, why not name them consistently, such as

• pycqa8 and pycqa257
• pycq8 and pycq257
• flake8-core and flake257

pydocstrings is vague about what it does about docstrings, which seems more confusing to me.

Agree. How about pydocstringlint? (im not a fan, as it is very long..)

I like @jirikuncar's pyfluff , but I feel it would also need some additional name component that indicates it is implementing pep 257. fluff doesnt strongly indicate that it is docstring related. Adding -docstring is very long and adds a bland part to the name.

Some other plays on 'pep':

• epp257 (where epp could stand for something like electronic pep purifier, ...) - conflicts with https://en.wikipedia.org/wiki/Extensible_Provisioning_Protocol / https://pypi.python.org/pypi/EPP
• dull257 (pep means enliven)
• pepper257 (pep is an abbreviation of pepper)
• spice257
• zest257
• zap257
• dsd, docstring_doctor, docstring_dr
• redocstring
• pydeknot

[sigmavirus24]

As they are coming under one umbrella, why not name them consistently, such as

• pycqa8 and pycqa257
• pycq8 and pycq257
• flake8-core and flake257

I have no clue what you're talking about. The PyCQA is merely an organization for similar/like-minded/related projects to live in. This also allows us to make sure there are enough maintainers in case someone goes AWOL. Are you proposing naming tools that are loosely associated after the organization itself?

Of your options, @jayvdb, pepper257 is interesting but I think it might cause confusion with:

• https://pypi.python.org/pypi/pepper
• https://pypi.python.org/pypi/pepper8
• https://pypi.python.org/pypi/pepper_kinematics

What about:

• check257
• checkdocstrings or check-docstrings

[gvanrossum]

I'm sorry, folks, the whole point of this issue is to not tie the tool's
name directly to the PEP's name. Keeping 257 as part of the name defeats
that for me. It should be crystal clear to users of the tool that when they
perceive a difference between the tool and the PEP they should talk to the
tool's developers (who then in turn might ask the PEP authors for
clarification -- but often the PEP is intentionally vague when there's an
issue that's not easily captured in a simple rule or where reasonable
people can disagree).

[Nurdok]

Guido, the tool currently provides a --convention flag where the user can choose an option for a known convention, such as pep257, numpy, etc.
Would keeping this option be problematic in your opinion? I do think that there is a rational in wanting to follow an official style guide.

[jirikuncar]

pycqa257doc with --convetion (pep257|numpy) option sounds like good candidate to me.

• pros: short, no 257 in name so Guido might be happy, 'doc' in name should give us enough freedom to implement other styles and checks;
• cons: missing 'strings' it might confuse users.

Another cool name is (update: py)dsd/ddr (Docstring Doctor) as @jayvdb proposed.

[sigmavirus24]

If we're looking at such a short name, distributions will have problems packaging the project. We should at least make it pydsd or pyddr.

On January 6, 2016 2:50:41 AM CST, Jiri Kuncar notifications@github.com wrote:

pycqa257doc with --convetion (pep257|numpy) option sounds
like good candidate to me.

• pros: short, no 257 in name so Guido might be happy, 'doc' in name
  should give us enough freedom to implement other styles and checks;
• cons: missing 'strings' it might confuse users.

Another cool name is dsd/ddr (Docstring Doctor) as @jayvdb proposed.

---

Reply to this email directly or view it on GitHub:
#172 (comment)

Sent from my Android device with K-9 Mail. Please excuse my brevity.

[sigmavirus24]

I have no issues with using pycqa in tool names but I don't think that's clear to users or helpful in naming things.

[gvanrossum]

That --pep257 option is fine. I always assumed that PCQA was an ironic
name, not something to use in the tool. To me, pydoclint or pydocstyle
sound best, but its your tool!

--Guido (mobile)
On Jan 6, 2016 7:07 AM, "Ian Cordasco" notifications@github.com wrote:

I have no issues with using pycqa in tool names but I don't think that's
clear to users or helpful in naming things.

—
Reply to this email directly or view it on GitHub
#172 (comment).

[sigmavirus24]

Yeah PyCQA was a joke on the code-quality mailing list. (Much like PyCA, PyPA, etc. are not originally meant to be entirely serious).

[sigmavirus24]

Also as part of the move of the project to the PyCQA, I think it will be cleaner if what we do is leave this repository exactly as it is with the exception of a notice of its deprecation in favor of whatever we end up calling the new project. The same notice should be published to the pep257 PyPI project with perhaps the final release being a meta-package that points people to installing "new-tool" the same way the py.test package points people at installing pytest.

The new project should effectively be a fork of this project but perhaps without the GitHub link between the two so there's no confusion as to the origins of the PyCQA project.

Alternatively, we can "move" this project via GitHub and then have GreenSteam fork it as "pep257" with the same notice. GitHub would handle redirects for us (from GreenSteam/pep257 -> PyCQA/"new name") so we don't actually need to preserve this if we'd also like to preserve the issue history in the PyCQA project. How that's handled, however, is between @Nurdok and @keleshev. I'm just offering options :)

[gvanrossum]

But why not use GitHub's redirection facilities? If you rename + give away the project, anyone going to the current project URL will be redirected to the new repo. IMO that's cleaner than forking (some folks will miss the notice in the README, you have two trackers, etc.)

[sigmavirus24]

@gvanrossum yeah, I know there was some discussion of "GreenSteam/pep257" still being a repository though. That's why I offered the other options to make that continue to be a thing. Further, any fork can turn off issues and have a bot to auto-close pull requests with a friendly message. I personally prefer the simple redirection method but that's just me.

[Nurdok]

• I don't want PyCQA in the new name. It's enough to be under the PyCQA organization.
• All suggestions with pep257 or 257 in them defeat the purpose.

Right now, pydoclint is my favorite, with pydocstyle as a runner up. The docstring doctor names are cute, but too long to say, IMO. I'll give it a day or two to settle in before I decide :)

[Nurdok]

I registered pydocstyle on PyPI, following discussion on the pep8 thread. @keleshev do you object transferring GreenSteam/pep257 to PyCQA? You said you wanted to create a new repository and link to it from the old one, but @gvanrossum suggests that Github's redirection facilities might be a better option. It's your call.

[sigmavirus24]

Whoever ends up moving this needs to give me a head's up. I need to make them an owner in the PyCQA so they can transfer the organization. Conversely, they can make me an owner here and I can transfer the repo for you.

[keleshev]

Using GitHub redirection facilities seems like a good choice, so that https://github.com/GreenSteam/pep257 will redirect to the new repo. However, I guess that many know this project by its current name, and not by the repo link, so they will be googling something like pep257 tool and not finding the repo. That's why I thought that keeping this repo as it is with a huge disclaimer "THIS REPO IS SUNSET, USE PYDOCSTYLE INSTEAD: link" would be more educational for the users and smooth the transition to the new name.

That's my concern, but I'm fine with either way. Don't want to drag this any longer, so @Nurdok—do what you think is best.

[Nurdok]

@sigmavirus24 We'll go with transfer + rename. Could you give me the permissions?

[sigmavirus24]

@Nurdok done.

[Nurdok]

The repository transfer and rename are done. We're now PyCQA/pydocstyle 👌
I'll start working on changing the codebase - readme, license, docs, entry points (while still leaving the old pep257 script for now, with a deprecation warning), etc.

[sigmavirus24]

I tested the redirect and it works great. 🎉 🍰

[lordmauve]

I'm sad about this. I think this will mean fewer people use the tool, when it would be better if more people do - or take other steps enforce docstring coverage and conventions, PEP257 or otherwise.

We should make it clear in the README that it is intended to check conformance to PEP257 but is not a reference implementation of said PEP.

[Nurdok]

@lordmauve don't worry, you will still be able to do --convention=pep257, and it will be the default convention.

[sigmavirus24]

@Nurdok I think you meant @lordmauve not lodagro ;)

[Nurdok]

Yep, my mistake (edited).

[Nurdok]

Done :)

[jayvdb]

project on openhub renamed
https://www.openhub.net/p/pydocstyle