Create FAQ documentation

[felix-hilden]

Hi, this PR creates a Frequently Asked Questions document for our users to read. Hopefully they actually read it too. Items included are: Black's non-API, AST safety, style stability, file discovery, Flake8 disagreements and Python 2 support. Hopefully I've got the answers down in general.

Anyways, a few points of contention:

• Folder vs single document: I decided to have them in a folder for the easy globbing and toc tree. The optimal scenario in my mind would be to have them in a single document and have an index on top. The issue with that is that it would have to be created manually which of course requires more work now and whenever a new item is added. Trivial? Maybe, I'll leave it up to you to decide 😄
• Top level placement: Richard, you said that you'd like for it to be quite visible, so I added right at the top after "Usage and configuration". Is that ok?
• Content: anything really. For example, you might not want the blunt, single-word initial answers. They do convey the most information, but the answers are concise anyway if we want to wipe them and let users read a bit. We might also want more prose at the top.

skip news? Also, I'll leave this as a draft so we can discuss a bit.

Closes #2176, closes #1946.

[ichard26]

Hey thanks for writing up a draft real quick! I got quite a bit of feedback so let's get started:

RE: Folder vs single document

I agree a single page FAQ would be better. The good news is that I found a RST directive that almost does what we want. It produces a nice TOC in the style of the TOCTREE but for the current document. Unfortunately the default styling with the current theme is IMO ugly:

Thankfully it's quite easy to fix this with some custom CSS:

.contents.topic {
  background: none;
  border: none;
}

We can add this CSS to docs/_static/custom.css which gets picked up by Sphinx.

Here's the markup you'll need to use this directive (yes, I still prefer MyST over RST):

```{contents}
:local:
:backlinks: none
```

OR in reStructuredText:

.. contents::
  :local:
  :backlinks: none

RE: Top level placement

I was more thinking putting it at the end of the "user guide" section, so after the "Guides" section. It's IMO a bit jarring to have a "Frequently Asked Questions" right after "Usage and Configuration".

[felix-hilden]

Thanks for the review! I didn't actually know about the contents directive, so thanks 😄 and thanks for essentially solving the issues for me! I think the most pressing issues have been addressed, so I'll make this wooden doll of a PR into a real boy now. If the ongoing discussions are solved in your opinion, I think it's good to go.

[ichard26]

Wait, I forgot about the changelog entry. Honestly I could go either way, I like adding documentation stuff to the changelog as an another way of saying "thanks!" but they're aren't exactly user facing changes.

[JelleZijlstra]

I think it's useful to add a changelog as a way of alerting users "here's this new useful page you can look at".

[felix-hilden]

There ya go!

[ichard26]

It's been two days without any activity (while having two reviews, one of them approving 😉) so I'm just going to merge. Thank you again @felix-hilden!