Completely rework the capitalization check algo in 'validate_rst_title_capitalization.py'
State: closed

- [ ] Modify file scripts/validate_rst_title_capitalization
- [ ] tests added / passed
- [ ] passes `black pandas`
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`

PR on rework of the script 'validate_rst_title_capitalization.py' to better handle the capitalization, the capitalization exceptions, with the use of exceptions in the form of tuples to allow different writings for a particular word. The idea is to be able to use two different types inside 'CAPITALIZATION_EXCEPTIONS': one-word string, or tuple containing a number of word elements, with different capitalization.
You can experiment it by replacing some exceptions inside 'CAPITALIZATION_EXCEPTIONS' by tuples containing several times the same exception with different capitalisations. I already did it for 'categorical' with ('categorical', 'Categorical')

Labels:
name: Docs
name: Code Style
description: Code style, linting, code_checks
name: Stale

Comments:
Hello @cleconte987! Thanks for updating this PR. We checked the lines you've touched for [PEP 8](https://www.python.org/dev/peps/pep-0008) issues, and found:



There are currently no PEP 8 issues detected in this Pull Request. Cheers! :beers: 

##### Comment last updated at 2020-10-25 20:34:49 UTC
@datapythonista 

Hello, this is a PR regarding the rework of the validation of capitalization in file scripts/validate_rst_title_capitalization.py
Sorry for the long delay. So if I understand you correctly, you would like this script to automatically modify documentation titles according to some rules, but not proposing the user the correct capitalization? Sorry but I have trouble understanding you on this one.
> Sorry for the long delay. So if I understand you correctly, you would like this script to automatically modify documentation titles according to some rules, but not proposing the user the correct capitalization? Sorry but I have trouble understanding you on this one.

This script is to validate, not to automatically modify titles. The current approach is, for a given title:
- Compute the right title capitalization given a title (e.g. for an input `section about sql` it will compute `Section about SQL`)
- If the capitalization doesn't match the one in the docs, it fails, and it reports to the user which should be the right capitalization (`Section about SQL` in the example)

The problem is that in some cases, the same word can be capitalized in different ways, depending to what refers. `The Index class` vs `The index in a list`. So, the above approach, is not feasible since there is no right capitalization anymore. What I'm saying is that instead of generating all the possible right capitalizations, and compare the existing one to all them, it makes more sense to forget about the right capitalization, which was obtained to show to the user on failures, and just validate word by word if it's correctly capitalized. The first word should start with uppercase, and the rest with lowercase, unless the word exists in the list of exceptions, with the capitalization found in the title.
This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.
@cleconte987 how is this going? Does this need another review? (If yes can you look at CI failures and ping when ready - either if failures resolved or unrelated)
Closing for now. @cleconte987 ping us whenever you'd like to continue and we'll reopen!