Improve documentation for SSL certificates

[bhrutledge]

Following up on #835 (and related issues linked with), it seems like Twine's docs could be more helpful on how to use the --cert and --client-cert options, maybe as a new sub-section under Configuration. I think it'd also be nice indicate common gotchas, esp. related to environment configuration.

I'm out of my depth here, so suggestions welcome.

[sigmavirus24]

I thought we had this in an older version of the docs and it was eliminated for "simplicity" when we switched themes and did other work to the docs. It was deemed useless back then if I remember correctly. Why is it suddenly useful now? Why do we expect people who don't search other resources in good faith to find it in the docs?

I think it'd also be nice indicate common gotchas, esp. related to environment configuration.

This sounds orthogonal and vague. How is this related to SSL certificates? What parts of the issue linked do you think relates to environment configuration?

[bhrutledge]

I thought we had this in an older version of the docs and it was eliminated for "simplicity" when we switched themes and did other work to the docs. It was deemed useless back then if I remember correctly.

I have no recollection of that, and nothing is jumping out at me from the commit history. Can you find it?

Why do we expect people who don't search other resources in good faith to find it in the docs?

I hesitate to make assumptions about the steps that someone took prior to opening an issue. That said, opening an issue when encountering a confusing error seems reasonable, esp. for newcomers who might not be familiar with other support resources. I wouldn't expect folks to find it in Twine's docs (though I suspect some would), but I think it would be nice to have a quick "canonical" reference that's tailored to Twine's usage that maintainers could link to before closing the issue. It seems like there's a recent example of this re: proxy support in #814.

I'd write this myself, but as I've said, I'm out of my depth, because this is not a need for me, so I would need guidance on setting up a test environment.

How is this related to SSL certificates? What parts of the issue linked do you think relates to environment configuration?

I think this stems from my lack of familiarity. I used the word "environment" to encompass system/OS/network configuration, which is where I mentally bucket SSL certificate issues.