Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create FAQ documentation #2247

Merged
merged 5 commits into from May 25, 2021
Merged

Create FAQ documentation #2247

merged 5 commits into from May 25, 2021

Conversation

felix-hilden
Copy link
Collaborator

@felix-hilden felix-hilden commented May 18, 2021

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 ichard26 self-requested a review May 18, 2021 16:00
docs/faq/items/black_api.md Outdated Show resolved Hide resolved
docs/faq/items/python2_support.md Outdated Show resolved Hide resolved
Copy link
Collaborator

@ichard26 ichard26 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Screenshot from 2021-05-22 17-36-06

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

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

Screenshot from 2021-05-22 17-40-37

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".

docs/faq/items/file_not_formatted.md Outdated Show resolved Hide resolved
docs/faq/items/python2_support.md Outdated Show resolved Hide resolved
docs/faq/items/python2_support.md Outdated Show resolved Hide resolved
@felix-hilden
Copy link
Collaborator Author

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.

@felix-hilden felix-hilden marked this pull request as ready for review May 23, 2021 17:58
@ichard26
Copy link
Collaborator

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
Copy link
Collaborator

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
Copy link
Collaborator Author

There ya go!

@ichard26
Copy link
Collaborator

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!

@ichard26 ichard26 merged commit 04518c3 into psf:main May 25, 2021
@ichard26 ichard26 added the T: documentation Improvements to the docs (e.g. new topic, correction, etc) label May 25, 2021
@felix-hilden felix-hilden deleted the docs-faq branch May 26, 2021 08:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
T: documentation Improvements to the docs (e.g. new topic, correction, etc)
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Docs: Let's create a "Common Issues & FAQ" document Document support plan for py2
3 participants