Add Docstring section to development docs

[zm711]

A companion documentation section to go with @alejoe91 #2134. This way future developers will be adequately warned about what is expected in the docstrings.

Read through the docstring section and let me know if you want me to include more info.

Other minor changes
*I restylized black to Black since that is their official name whereas black is the package (similar to this repo :) )
* added a note about fmt skip vs fmt off for black
* couple typo fixes

One question is near the bottom the section originally said edit the travis.yml, but I assumed it was suppose to be edit the pyproject to add the dependencies to the test section, but if I'm wrong correct that section.

[h-mayorquin]

This looks good to me. I did this the first time and this is an improvement upon it. I have been meaning to add @alejoe91 convention for a while so I am thankful that @zm711 decided to do this.

I added two small suggestions that are up to @zm711 to follow up or not.

[zm711]

While you're checking this out @h-mayorquin. I know you added the datalad instructions but I for one can't get datalad working on Mac ( m-series). I think there is a mismatch between datalad, git-annex, and brew. I'll update those instructions if I can figure it out, but just wanted that on your radar in case you know any magic tips for getting it to work.

[h-mayorquin]

@zm711 I was kind of proud that I got datalad working for all the three OSs in the CI at some point in time. This was accomplished using those instructions. Because of the Sam moratorium on testing we ended up not using that but ... flawed human as I am, I wanted to keep those instructions somewhere and they ended up there.

In retrospective, this is wrong. We are doing duplication by keeping those instructions there and, even worse, making promises that we don't know if we can keep ("the method works"). We should just point out to the documentation in datalad and be done with it.

Plus, now that we have good generators we will be getting rid of Datalad for core testing (which is great!) so this is even less necessary as we will only be needing if for extractor testing.

[zm711]

First off I always super appreciate all your hard work getting the ci working @h-mayorquin!

Plus, now that we have good generators we will be getting rid of Datalad for core testing (which is great!) so this is even less necessary as we will only be needing if for extractor testing.

I agree. I think switching the examples to the generators (in the modules gallery) would be super beneficial. Because right now we allow people to download the scripts, but the scripts will fail if the user doesn't have datalad.

We should just point out to the documentation in datalad and be done with it.

I'll change the datalad section right now just so that we don't "over-promise".

(I was able to get datalad with windows, but I had to specify my git-annex version in the datalad installer and jump through a couple hoops, so yeah I think the packages are just changing at different rates, which makes it hard to have the instructions just work).

Also just as an fyi (since you worked so hard on the ci). I recently tried to run the whole test-suite on windows (I ended about 7/8 of the way through) and ended up with something like 50-60 test failures. Mostly due to shutil.rmtree being blocked by Windows permssion errors.

[h-mayorquin]

Thanks for testing this on windows.

In the last meeting we discussed testing. I am hoping that by the end of this week and next week I will be working in some outstanding* maintenance issues which will include testing.

(I just realized that this is synonym with great which I find strange)