Skip to content

Create FAQ documentation#2247

Merged
ichard26 merged 5 commits intopsf:mainfrom
felix-hilden:docs-faq
May 25, 2021
Merged

Create FAQ documentation#2247
ichard26 merged 5 commits intopsf:mainfrom
felix-hilden:docs-faq

Conversation

@felix-hilden
Copy link
Copy Markdown
Collaborator

@felix-hilden felix-hilden commented May 18, 2021 •
edited
Loading

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
JelleZijlstra
JelleZijlstra reviewed May 18, 2021
View reviewed changes
Comment thread docs/faq/items/black_api.md Outdated
Comment thread docs/faq/items/python2_support.md Outdated
ichard26
ichard26 requested changes May 22, 2021
View reviewed changes
Copy link
Copy Markdown
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".

Comment thread docs/faq/items/file_not_formatted.md Outdated
Comment thread docs/faq/items/python2_support.md Outdated
Comment thread docs/faq/items/python2_support.md Outdated
@felix-hilden
Copy link
Copy Markdown
Collaborator Author

felix-hilden commented May 23, 2021

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

ichard26 commented May 23, 2021

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

JelleZijlstra commented May 23, 2021

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

felix-hilden commented May 23, 2021

There ya go!

@felix-hilden felix-hilden mentioned this pull request May 23, 2021
Closed
@ichard26
Copy link
Copy Markdown
Collaborator

ichard26 commented May 25, 2021

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

Reviewers

@JelleZijlstra JelleZijlstra JelleZijlstra left review comments

@ichard26 ichard26 ichard26 approved these changes

Assignees

No one assigned

Labels

T: documentation Improvements to the docs (e.g. new topic, correction, etc)

Projects

None yet

Milestone

No milestone

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

@felix-hilden @ichard26 @JelleZijlstra