Pylint hosting on ReadTheDocs prevents successful searches
Googling for "pylint pylintrc" gives me the first hit as https://docs.pylint.org/en/1.6.0/run.html. This lands me on https://docs.pylint.org/en/1.6.0/run.html, asking me to login. I have a login, and clicking "Login" sends me to https://readthedocs.org/dashboard/, spoiling the google search. In fact, searching on google only shows me that something might be there. I have to search *again* on ReadTheDocs, which isn't friendly at all. Poking around until I find a search box at https://pylint.readthedocs.io/en/latest/, I type in "pylintrc", which returns the *same bloody page* (OK, yes, it has this helpful bit: https://pylint.readthedocs.io/en/latest/?highlight=pylintrc, which does exactly...nothing.) So I'm stuck trolling around in the full docs there. Instead, I should just pull down the source code, and do my own grep -r. I feel like I've been violated. -- -QM Quantum Mechanics: The dreams stuff is made of
On Fri, Jan 26, 2018 at 6:05 AM, Quantum Mechanic <quantum.mechanic.1964@gmail.com> wrote:
Googling for "pylint pylintrc" gives me the first hit as https://docs.pylint.org/en/1.6.0/run.html.
This lands me on https://docs.pylint.org/en/1.6.0/run.html, asking me to login. I have a login, and clicking "Login" sends me to https://readthedocs.org/dashboard/, spoiling the google search.
I was not asked to log into anything on that site. You'll need to provide a whole lot more detail.
In fact, searching on google only shows me that something might be there. I have to search *again* on ReadTheDocs, which isn't friendly at all.
Poking around until I find a search box at https://pylint.readthedocs.io/en/latest/, I type in "pylintrc", which returns the *same bloody page* (OK, yes, it has this helpful bit: https://pylint.readthedocs.io/en/latest/?highlight=pylintrc, which does exactly...nothing.)
So I'm stuck trolling around in the full docs there. Instead, I should just pull down the source code, and do my own grep -r.
I feel like I've been violated.
This sounds like an attempt to be humorous at the expense of people who have actually been physically violated. That isn't acceptable on this list and is not tolerated by any mailing list hosted on python.org. Please refrain from this in the future.
On Fri, Jan 26, 2018 at 09:15:43AM -0600, Ian Stapleton Cordasco wrote:
This sounds like an attempt to be humorous at the expense of people who have actually been physically violated. That isn't acceptable on this list and is not tolerated by any mailing list hosted on python.org. Please refrain from this in the future.
Ian, you are gate-keeping and telling the poster how he or she should feel. Please don't do that, it is a hostile and aggressive thing to do. You have no right to tell the OP that he or she *shouldn't* feel violated by an experience which he clearly experienced as frustrating and painful. Who are you to say that (s)he didn't, or shouldn't, have felt violated? And before you dismiss me (as I expect your initial reaction will be) both my wife and I are "people who have actually been physically violated". Your defence of our feelings, while well-intentioned, is neither needed nor wanted. I'm sure you thought you were doing the right thing, but we don't need you to act as gate-keeper telling us when we are being made fun of. We can decide for ourselves whether to interpret the OP's words as being at our expense or a genuine heartfelt sense of anguish at a hostile user-experience. Of course the OP's experience with Google and ReadTheDocs is not objectively as awful as what my wife has been through, or even for that matter me, but we shouldn't dismiss the mental pain of an ugly and frustrating user experience as any less real just because it didn't involve an actual knife being held to somebody's throat. Please don't be so hostile to a newcomer who has taken the time to report a problem on this list and did nothing to deserve the given reaction. At the *very least*, we as a community ought to give newcomers the benefit of the doubt and interpret the OP's comment as nothing more than hyperbole rather than assuming the worst ("...at the expense of..."). Thank you. Steve
Alright everyone, so what are we going to do about that? The search functionality looks fine to me in general on [1]. And the search box is in a logical place, in the sidebar. Maybe using a different, more modern theme may improve the user experience slightly, though. I guess redirecting every access on "docs.pylint.org" to "pylint.readthedocs.io" (for both HTTP and HTTPS) will do away with the largest part of reader confusion. Is this something we can help fixing, e.g. by a PR? Regards, Peter [1] https://pylint.readthedocs.io/en/latest/search.html?q=pylintrc
Oh! I was---almost---wrong! There _is_ a bug obviously in the docs (generator configuration?). Because the search results on "pylint.readthedocs.io" all include links to "docs.pylint.org", thus redirecting requests to the documentation index ("Pylint User Manual"). This issue has already been reported at https://github.com/PyCQA/pylint/issues/1600 "Almost" wrong, because: A permanent redirect (including the address path) would also cover that problem. Peter
If you have a Bitbucket account please vote for this bug if you want the redirect (and the docs) to be working as described. - https://bitbucket.org/logilab/pylint.org/issues/16 Still yet, there is investigation needed why the old domain name ends up in the generated docs. Peter
On Jan 26, 2018, at 8:14 AM, Steven D'Aprano <steve@pearwood.info> wrote:
On Fri, Jan 26, 2018 at 09:15:43AM -0600, Ian Stapleton Cordasco wrote:
This sounds like an attempt to be humorous at the expense of people who have actually been physically violated. That isn't acceptable on this list and is not tolerated by any mailing list hosted on python.org. Please refrain from this in the future.
Ian, you are gate-keeping and telling the poster how he or she should feel. Please don't do that, it is a hostile and aggressive thing to do. You have no right to tell the OP that he or she *shouldn't* feel violated by an experience which he clearly experienced as frustrating and painful. Who are you to say that (s)he didn't, or shouldn't, have felt violated?
All, Jumping to conclusions about people's intents will continue along an unproductive path to improve the documentation experience. Let's try to keep this discussion on topic. Giving everyone the benefit of the doubt of being well intentioned, I would appreciate keeping any future discussion on the topic of the documentation search. Here's my thoughts for each of you as we move forward: - Thank you Quantum Mechanic for reporting the issue. - Thank you Ian for your empathy and respect for the community. - Thank you Steven for stressing that we "should" be a welcoming community to new and existing contributors. I just returned from PyCascades where Brett Cannon gave a great talk on open source community: https://www.youtube.com/watch?v=HiWfqMbJ3_8 <https://www.youtube.com/watch?v=HiWfqMbJ3_8> Thank you, Carol Willing
And before you dismiss me (as I expect your initial reaction will be) both my wife and I are "people who have actually been physically violated". Your defence of our feelings, while well-intentioned, is neither needed nor wanted. I'm sure you thought you were doing the right thing, but we don't need you to act as gate-keeper telling us when we are being made fun of. We can decide for ourselves whether to interpret the OP's words as being at our expense or a genuine heartfelt sense of anguish at a hostile user-experience.
Of course the OP's experience with Google and ReadTheDocs is not objectively as awful as what my wife has been through, or even for that matter me, but we shouldn't dismiss the mental pain of an ugly and frustrating user experience as any less real just because it didn't involve an actual knife being held to somebody's throat.
Please don't be so hostile to a newcomer who has taken the time to report a problem on this list and did nothing to deserve the given reaction. At the *very least*, we as a community ought to give newcomers the benefit of the doubt and interpret the OP's comment as nothing more than hyperbole rather than assuming the worst ("...at the expense of...").
Thank you.
Steve _______________________________________________ code-quality mailing list code-quality@python.org https://mail.python.org/mailman/listinfo/code-quality
On 26/01/18 13:05, Quantum Mechanic wrote:
Googling for "pylint pylintrc" gives me the first hit as https://docs.pylint.org/en/1.6.0/run.html.
This lands me on https://docs.pylint.org/en/1.6.0/run.html, asking me to login. I have a login, and clicking "Login" sends me to https://readthedocs.org/dashboard/, spoiling the google search.
This page doesn't ask me for login.
In fact, searching on google only shows me that something might be there. I have to search *again* on ReadTheDocs, which isn't friendly at all.
This is something you should complain about to Google. That bloody thing, as good is it might be, is still not that good at mind reading, and presenting you the exact information you want, and only that information, even when you provide ample information about what exactly you are after, like in your case with even *two* words. ;-)
Poking around until I find a search box at https://pylint.readthedocs.io/en/latest/, I type in "pylintrc", which returns the *same bloody page* (OK, yes, it has this helpful bit: https://pylint.readthedocs.io/en/latest/?highlight=pylintrc, which does exactly...nothing.)
This also doesn't happen for me. I get a page with search results (long link, might be broken into more than one line in Email): https://pylint.readthedocs.io/en/latest/search.html?q=pylintrc&check_keywords=yes&area=default Ciao, Marc 'BlackJack' Rintsch -- Lottery: A tax on people who are bad at math.
Hi, I'm sorry I riled everyone up. My apologies. === Trying to reproduce === Getting back to this today, I'm not sent to readthedocs.org. I'll chalk that up to the interwebz demons fiddling around (could be anywhere between my $work, Google, and your end, including various intermediaries). Now, back to the next problem. There doesn't seem to be any documentation on the fields in .pylintrc. I'm specifically looking for init-hook help. I can't find anything of substance in the html docs, so I download the PDF and search for "init-hook". There are 6 hits, most only mentions. Finally, it occurs to me (from the nature of the change summaries in the PDF) that this is probably a command line argument. Low and behold, pylint --help has a blurb. (As an aside, I'm wondering how to format this well for command line, due to the significant whitespace feature, but that's a problem for another day.) === Problem 1 === Search not helpful =============== For me, the web docs are not that helpful for searching, as it doesn't get me any closer. Take this screenshot of a search for init-hook: The first link goes to http://docs.pylint.org/en/latest/user_guide/run.html?highlight=init-hook, which looks like this: ...which I had before. === Problem 2 === Command line help not online =============== The command line help does not exist online or in the PDF in except in brief, as far as I can see. Perhaps this is intentional? (It makes it harder to post Stack Exchange answers, but that's SEP.) === Problem 3 === How to include multiline code in .pylintrc file in the init-hook section. =============== This doesn't seem to be covered anywhere in the docs, but is an obvious use case. On Fri, Jan 26, 2018 at 12:05 PM, Quantum Mechanic < quantum.mechanic.1964@gmail.com> wrote:
Googling for "pylint pylintrc" gives me the first hit as https://docs.pylint.org/en/1.6.0/run.html.
This lands me on https://docs.pylint.org/en/1.6.0/run.html, asking me to login. I have a login, and clicking "Login" sends me to https://readthedocs.org/dashboard/, spoiling the google search.
In fact, searching on google only shows me that something might be there. I have to search *again* on ReadTheDocs, which isn't friendly at all.
Poking around until I find a search box at https://pylint.readthedocs. io/en/latest/, I type in "pylintrc", which returns the *same bloody page* (OK, yes, it has this helpful bit: https://pylint. readthedocs.io/en/latest/?highlight=pylintrc, which does exactly...nothing.)
So I'm stuck trolling around in the full docs there. Instead, I should just pull down the source code, and do my own grep -r.
I feel like I've been violated.
-- -QM Quantum Mechanics: The dreams stuff is made of
-- -QM Quantum Mechanics: The dreams stuff is made of
Hi Quantum Mechanic, Web Search ------------- I went back and checked a Google search and a Duck Duck Go search on "pylint". - On Duck Duck Go, https://www.pylint.org <https://www.pylint.org/> and https://pylint.readthedocs.io/en/latest/ <https://pylint.readthedocs.io/en/latest/> are the first two hits. - On Google, https://www.pylint.org <https://www.pylint.org/> and https://pypi.python.org/pypi/pylint <https://pypi.python.org/pypi/pylint> are the first two hits. For a "pylint pylintrc" search: - On Duck Duck Go, the website and v2.0 ReadTheDocs page are in the top four hits. - On Google, the v1.6.5 ReadThe Docs page and the GitHub repo are in the top two hits. I'm not an SEO person but someone else may have a suggestion on how to improve the hit rate for v2.0 ReadTheDocs on Google. ReadTheDocs Search ----------------------- When I try searching on "pylintrc" from the search box, I do receive 6 hits. Unfortunately, each of those when clicked redirect to the docs home page. Searching for "init-hook", I see the same behavior. This is a bug/configuration error in Sphinx setup or the theme of some sort. There is an open issue on the GitHub repo: https://github.com/PyCQA/pylint/issues/1600 <https://github.com/PyCQA/pylint/issues/1600> Next actions -------------- I've added this summary to the open issue: https://github.com/PyCQA/pylint/issues/1600#issuecomment-361977477 <https://github.com/PyCQA/pylint/issues/1600#issuecomment-361977477> Perhaps labeling this doc issue as Help Wanted as well would be useful. Regards, Carol
On Jan 30, 2018, at 8:46 AM, Quantum Mechanic <quantum.mechanic.1964@gmail.com> wrote:
Hi,
I'm sorry I riled everyone up. My apologies.
=== Trying to reproduce === Getting back to this today, I'm not sent to readthedocs.org <http://readthedocs.org/>. I'll chalk that up to the interwebz demons fiddling around (could be anywhere between my $work, Google, and your end, including various intermediaries).
Now, back to the next problem. There doesn't seem to be any documentation on the fields in .pylintrc. I'm specifically looking for init-hook help.
I can't find anything of substance in the html docs, so I download the PDF and search for "init-hook". There are 6 hits, most only mentions.
Finally, it occurs to me (from the nature of the change summaries in the PDF) that this is probably a command line argument. Low and behold, pylint --help has a blurb. (As an aside, I'm wondering how to format this well for command line, due to the significant whitespace feature, but that's a problem for another day.)
=== Problem 1 === Search not helpful ===============
For me, the web docs are not that helpful for searching, as it doesn't get me any closer. Take this screenshot of a search for init-hook:
The first link goes to http://docs.pylint.org/en/latest/user_guide/run.html?highlight=init-hook <http://docs.pylint.org/en/latest/user_guide/run.html?highlight=init-hook>, which looks like this:
...which I had before.
=== Problem 2 === Command line help not online ===============
The command line help does not exist online or in the PDF in except in brief, as far as I can see. Perhaps this is intentional? (It makes it harder to post Stack Exchange answers, but that's SEP.)
=== Problem 3 === How to include multiline code in .pylintrc file in the init-hook section. ===============
This doesn't seem to be covered anywhere in the docs, but is an obvious use case.
On Fri, Jan 26, 2018 at 12:05 PM, Quantum Mechanic <quantum.mechanic.1964@gmail.com <mailto:quantum.mechanic.1964@gmail.com>>wrote: Googling for "pylint pylintrc" gives me the first hit as https://docs.pylint.org/en/1.6.0/run.html <https://docs.pylint.org/en/1.6.0/run.html>.
This lands me on https://docs.pylint.org/en/1.6.0/run.html <https://docs.pylint.org/en/1.6.0/run.html>, asking me to login. I have a login, and clicking "Login" sends me to https://readthedocs.org/dashboard/ <https://readthedocs.org/dashboard/>, spoiling the google search.
In fact, searching on google only shows me that something might be there. I have to search *again* on ReadTheDocs, which isn't friendly at all.
Poking around until I find a search box at https://pylint.readthedocs.io/en/latest/ <https://pylint.readthedocs.io/en/latest/>, I type in "pylintrc", which returns the *same bloody page* (OK, yes, it has this helpful bit: https://pylint.readthedocs.io/en/latest/?highlight=pylintrc <https://pylint.readthedocs.io/en/latest/?highlight=pylintrc>, which does exactly...nothing.)
So I'm stuck trolling around in the full docs there. Instead, I should just pull down the source code, and do my own grep -r.
I feel like I've been violated.
-- -QM Quantum Mechanics: The dreams stuff is made of
-- -QM Quantum Mechanics: The dreams stuff is made of <Screen Shot 2018-01-30 at 16.19.05.png><Screen Shot 2018-01-30 at 16.20.46.png>_______________________________________________ code-quality mailing list code-quality@python.org <mailto:code-quality@python.org> https://mail.python.org/mailman/listinfo/code-quality <https://mail.python.org/mailman/listinfo/code-quality>
Hi Carol, Thank you very much for your follow up, I'm glad to know I wasn't completely out to lunch on the day. I'm "watching" the issue page. I'll be sure to search the issue system if I come across problems in the future. Cheers, QM On Wed, Jan 31, 2018 at 3:59 PM, Carol Willing < willingc@willingconsulting.com> wrote:
Hi Quantum Mechanic,
Web Search ------------- I went back and checked a Google search and a Duck Duck Go search on "pylint".
- On Duck Duck Go, https://www.pylint.org and htt ps://pylint.readthedocs.io/en/latest/ are the first two hits. - On Google, https://www.pylint.org and https://pypi.python.org/pypi/ pylint are the first two hits.
For a "pylint pylintrc" search:
- On Duck Duck Go, the website and v2.0 ReadTheDocs page are in the top four hits. - On Google, the v1.6.5 ReadThe Docs page and the GitHub repo are in the top two hits.
I'm not an SEO person but someone else may have a suggestion on how to improve the hit rate for v2.0 ReadTheDocs on Google.
ReadTheDocs Search ----------------------- When I try searching on "pylintrc" from the search box, I do receive 6 hits. Unfortunately, each of those when clicked redirect to the docs home page. Searching for "init-hook", I see the same behavior. This is a bug/configuration error in Sphinx setup or the theme of some sort.
There is an open issue on the GitHub repo: https://github.com/ PyCQA/pylint/issues/1600
Next actions --------------
I've added this summary to the open issue: https://github.com/ PyCQA/pylint/issues/1600#issuecomment-361977477
Perhaps labeling this doc issue as Help Wanted as well would be useful.
Regards,
Carol
On Jan 30, 2018, at 8:46 AM, Quantum Mechanic < quantum.mechanic.1964@gmail.com> wrote:
Hi,
I'm sorry I riled everyone up. My apologies.
=== Trying to reproduce === Getting back to this today, I'm not sent to readthedocs.org. I'll chalk that up to the interwebz demons fiddling around (could be anywhere between my $work, Google, and your end, including various intermediaries).
Now, back to the next problem. There doesn't seem to be any documentation on the fields in .pylintrc. I'm specifically looking for init-hook help.
I can't find anything of substance in the html docs, so I download the PDF and search for "init-hook". There are 6 hits, most only mentions.
Finally, it occurs to me (from the nature of the change summaries in the PDF) that this is probably a command line argument. Low and behold, pylint --help has a blurb. (As an aside, I'm wondering how to format this well for command line, due to the significant whitespace feature, but that's a problem for another day.)
=== Problem 1 === Search not helpful ===============
For me, the web docs are not that helpful for searching, as it doesn't get me any closer. Take this screenshot of a search for init-hook:
The first link goes to http://docs.pylint.org/en/ latest/user_guide/run.html?highlight=init-hook, which looks like this:
...which I had before.
=== Problem 2 === Command line help not online ===============
The command line help does not exist online or in the PDF in except in brief, as far as I can see. Perhaps this is intentional? (It makes it harder to post Stack Exchange answers, but that's SEP.)
=== Problem 3 === How to include multiline code in .pylintrc file in the init-hook section. ===============
This doesn't seem to be covered anywhere in the docs, but is an obvious use case.
On Fri, Jan 26, 2018 at 12:05 PM, Quantum Mechanic <quantum.mechanic. 1964@gmail.com>wrote:
Googling for "pylint pylintrc" gives me the first hit as https://docs.pylint.org/en/1.6.0/run.html.
This lands me on https://docs.pylint.org/en/1.6.0/run.html, asking me to login. I have a login, and clicking "Login" sends me to https://readthedocs.org/dashboard/, spoiling the google search.
In fact, searching on google only shows me that something might be there. I have to search *again* on ReadTheDocs, which isn't friendly at all.
Poking around until I find a search box at https://pylint.readthedocs. io/en/latest/, I type in "pylintrc", which returns the *same bloody page* (OK, yes, it has this helpful bit: https://pylint.readthedoc s.io/en/latest/?highlight=pylintrc, which does exactly...nothing.)
So I'm stuck trolling around in the full docs there. Instead, I should just pull down the source code, and do my own grep -r.
I feel like I've been violated.
-- -QM Quantum Mechanics: The dreams stuff is made of
-- -QM Quantum Mechanics: The dreams stuff is made of <Screen Shot 2018-01-30 at 16.19.05.png><Screen Shot 2018-01-30 at 16.20.46.png>_______________________________________________ code-quality mailing list code-quality@python.org https://mail.python.org/mailman/listinfo/code-quality
-- -QM Quantum Mechanics: The dreams stuff is made of
participants (6)
-
Carol Willing
-
Ian Stapleton Cordasco
-
Marc 'BlackJack' Rintsch
-
Peter Bittner
-
Quantum Mechanic
-
Steven D'Aprano