Docstring cleanup: "default None", doi

[echedey-ls]

• Closes "default None" in docstring parameter descriptions considered harmful #1574 . All changes at the bottom.
• I am familiar with the contributing guidelines
• [ ] Tests added
• [ ] Updates entries in docs/sphinx/source/reference for API changes.
• [ ] Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
• Current code includes numpydoc compliant docstrings, examples, and comments everywhere.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels (including remote-data) and Milestone are assigned to the Pull Request and linked Issue.

Cherry-picked commits from #1790 and repeated the process with the regexes, with little changes to them.

Changes in this PR

1. Changes excessive use of parentheses in defaults
   return_components: bool (optional, default=False) -> return_components : bool, default False
2. default None -> optional ("default None" in docstring parameter descriptions considered harmful #1574)
3. If None -> If not specified
4. Inexistent DOI roles are now roles, e. g.: DOI: 10... -> :doi:`10...`

[echedey-ls]

regex DOI: ... to :doi:`...`

Done!

[cwhanse]

Thanks @echedey-ls

There's more markdown to be done in the descriptions of parameters this touches, if you feel it is in scope. I stopped suggesting it.

@pvlib/pvlib-maintainer it is questionable in my mind whether module_parameters, inverter_parameters and the like should be optional for instantiating a ModelChain. The ModelChain is created, true, but nothing runs.

[cwhanse]

@echedey-ls thanks for the work on this. If we don't get all instances of default None in this PR, we can do more later.

[echedey-ls]

I had to iterate a bit more... At first glance I thought very constraining regexes were enough, but even trailing dots were messing with that. I think all have been addressed for now.

[echedey-ls]

This should be ready to go, unless anything else wants to be done!

[kandersolar]

LGTM, thanks @echedey-ls! Might be worth leaving a comment on this PR with a list of the final set of regexes you used for this PR, in case we want to re-run something like this in the future.

it is questionable in my mind whether module_parameters, inverter_parameters and the like should be optional for instantiating a ModelChain. The ModelChain is created, true, but nothing runs.

@cwhanse I'm not sure what you mean. ModelChain doesn't take module_parameters or inverter_parameters.

[echedey-ls]

None regexes

These go by order:
F: (?<spaces>\s{8}|\s{4})(?<name>\w*)\s?: (?<type>.*) \(optional, default=(?<default>.*)\)$
Manually fix every match. This is a very constraining regex.

F1: (?<spaces> {8}| {4})(?<name>\w*) ?: (?<type>.*), default:? None\.?
F2: (?<spaces> {8}| {4})(?<name>\w*) ?: [Nn]one(?:,| or) (?<types>.*)
F3: (?<spaces> {8}| {4})(?<name>\w*) ?: (?<type>.*) or [nN]one, optional
R: $1$2 : $3, optional
Note: F3 requires special attention to commas.

F: (?<spaces> {8}| {4})(?<name>\w*) ?: [Nn]one, (?<type>.*), default:? (?<def>.*)\.?
R: $1$2 : $3, default $4

F: (?<spaces> {8}| {4})(?<name>\w*) ?: (?<types>.*) or [Nn]one(?<trailing>.*)
R: $1$2 : $3$4

F: If None
R: If not specified,

DOI regexes:

Regex find: (?:doi|DOI):(?!`)\s?(.*?)(\.\n|\n)
Replace: :doi:`$1`$2

Some of them could be changed to be more flexible, but I wanted the least number of false positives. I'm looking at the excessive-parentheses regex, they are really ugly in the web.

[kandersolar]

With no objections, time to merge! Thanks again @echedey-ls :)