-
Notifications
You must be signed in to change notification settings - Fork 3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' into release/20.2.4
- Loading branch information
Showing
196 changed files
with
3,391 additions
and
1,434 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,14 +1,11 @@ | ||
| # Ref: https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser | ||
| blank_issues_enabled: true # default | ||
| contact_links: | ||
| - name: 🤷💻🤦 Discourse | ||
| - name: 💬 Discourse | ||
| url: https://discuss.python.org/c/packaging | ||
| about: | | ||
| Please ask typical Q&A here: general ideas for Python packaging, | ||
| questions about structuring projects and so on | ||
| - name: '💬 IRC: #pypa @ Freenode' | ||
| url: https://webchat.freenode.net/#pypa | ||
| about: Chat with devs | ||
| - name: 📝 PyPA Code of Conduct | ||
| url: https://www.pypa.io/en/latest/code-of-conduct/ | ||
| about: ❤ Be nice to other members of the community. ☮ Behave. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,165 @@ | ||
| """A sphinx extension for collecting per doc feedback.""" | ||
|
|
||
| from __future__ import annotations | ||
|
|
||
| from itertools import chain | ||
| from typing import TYPE_CHECKING | ||
|
|
||
| if TYPE_CHECKING: | ||
| from typing import Dict, List, Union | ||
|
|
||
| from sphinx.application import Sphinx | ||
|
|
||
|
|
||
| DEFAULT_DOC_LINES_THRESHOLD = 250 | ||
| RST_INDENT = 4 | ||
| EMAIL_INDENT = 6 | ||
|
|
||
|
|
||
| def _modify_rst_document_source_on_read( | ||
| app: Sphinx, | ||
| docname: str, | ||
| source: List[str], | ||
| ) -> None: | ||
| """Add info block to top and bottom of each document source. | ||
| This function modifies RST source in-place by adding an admonition | ||
| block at the top and the bottom of each document right after it's | ||
| been read from disk preserving :orphan: at top, if present. | ||
| """ | ||
| admonition_type = app.config.docs_feedback_admonition_type | ||
| big_doc_lines = app.config.docs_feedback_big_doc_lines | ||
| escaped_email = app.config.docs_feedback_email.replace(' ', r'\ ') | ||
| excluded_documents = set(app.config.docs_feedback_excluded_documents) | ||
| questions_list = app.config.docs_feedback_questions_list | ||
|
|
||
| valid_admonitions = { | ||
| 'attention', 'caution', 'danger', 'error', 'hint', | ||
| 'important', 'note', 'tip', 'warning', 'admonition', | ||
| } | ||
|
|
||
| if admonition_type not in valid_admonitions: | ||
| raise ValueError( | ||
| 'Expected `docs_feedback_admonition_type` to be one of ' | ||
| f'{valid_admonitions} but got {admonition_type}.' | ||
| ) | ||
|
|
||
| if not questions_list: | ||
| raise ValueError( | ||
| 'Expected `docs_feedback_questions_list` to list questions ' | ||
| 'but got none.' | ||
| ) | ||
|
|
||
| if docname in excluded_documents: | ||
| # NOTE: Completely ignore any document | ||
| # NOTE: listed in 'docs_feedback_excluded_documents'. | ||
| return | ||
|
|
||
| is_doc_big = source[0].count('\n') >= big_doc_lines | ||
|
|
||
| questions_list_rst = '\n'.join( | ||
| f'{" " * RST_INDENT}{number!s}. {question}' | ||
| for number, question in enumerate(questions_list, 1) | ||
| ) | ||
| questions_list_urlencoded = ( | ||
| '\n'.join( | ||
| f'\n{" " * RST_INDENT}{number!s}. {question} ' | ||
| for number, question in enumerate( | ||
| chain( | ||
| (f'Document: {docname}. Page URL: https://', ), | ||
| questions_list, | ||
| ), | ||
| ) | ||
| ). | ||
| rstrip('\r\n\t '). | ||
| replace('\r', '%0D'). | ||
| replace('\n', '%0A'). | ||
| replace(' ', '%20') | ||
| ) | ||
|
|
||
| admonition_msg = rf""" | ||
| **Did this article help?** | ||
| We are currently doing research to improve pip's documentation | ||
| and would love your feedback. | ||
| Please `email us`_ and let us know{{let_us_know_ending}} | ||
| {{questions_list_rst}} | ||
| .. _email us: | ||
| mailto:{escaped_email}\ | ||
| ?subject=[Doc:\ {docname}]\ Pip\ docs\ feedback\ \ | ||
| (URL\:\ https\://)\ | ||
| &body={questions_list_urlencoded} | ||
| """ | ||
| let_us_know_ending = ':' | ||
|
|
||
| info_block_bottom = ( | ||
| f'.. {admonition_type}::\n\t\t{admonition_msg.format_map(locals())}\n' | ||
| ) | ||
|
|
||
| questions_list_rst = '' | ||
| let_us_know_ending = ( | ||
| ' why you came to this page and what on it helped ' | ||
| 'you and what did not. ' | ||
| '(:issue:`Read more about this research <8517>`)' | ||
| ) | ||
| info_block_top = '' if is_doc_big else ( | ||
| f'.. {admonition_type}::\n\t\t{admonition_msg.format_map(locals())}\n' | ||
| ) | ||
|
|
||
| orphan_mark = ':orphan:' | ||
| is_orphan = orphan_mark in source[0] | ||
| if is_orphan: | ||
| source[0].replace(orphan_mark, '') | ||
| else: | ||
| orphan_mark = '' | ||
|
|
||
| source[0] = '\n\n'.join(( | ||
| orphan_mark, info_block_top, source[0], info_block_bottom, | ||
| )) | ||
|
|
||
|
|
||
| def setup(app: Sphinx) -> Dict[str, Union[bool, str]]: | ||
| """Initialize the Sphinx extension. | ||
| This function adds a callback for modifying the document sources | ||
| in-place on read. | ||
| It also declares the extension settings changable via :file:`conf.py`. | ||
| """ | ||
| rebuild_trigger = 'html' # rebuild full html on settings change | ||
| app.add_config_value( | ||
| 'docs_feedback_admonition_type', | ||
| default='important', | ||
| rebuild=rebuild_trigger, | ||
| ) | ||
| app.add_config_value( | ||
| 'docs_feedback_big_doc_lines', | ||
| default=DEFAULT_DOC_LINES_THRESHOLD, | ||
| rebuild=rebuild_trigger, | ||
| ) | ||
| app.add_config_value( | ||
| 'docs_feedback_email', | ||
| default='Docs UX Team <docs-feedback+ux/pip.pypa.io@pypa.io>', | ||
| rebuild=rebuild_trigger, | ||
| ) | ||
| app.add_config_value( | ||
| 'docs_feedback_excluded_documents', | ||
| default=set(), | ||
| rebuild=rebuild_trigger, | ||
| ) | ||
| app.add_config_value( | ||
| 'docs_feedback_questions_list', | ||
| default=(), | ||
| rebuild=rebuild_trigger, | ||
| ) | ||
|
|
||
| app.add_css_file('important-admonition.css') | ||
| app.connect('source-read', _modify_rst_document_source_on_read) | ||
|
|
||
| return { | ||
| 'parallel_read_safe': True, | ||
| 'parallel_write_safe': True, | ||
| 'version': 'builtin', | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| .admonition.important { | ||
| background-color: rgb(219, 250, 244); | ||
| border: 1px solid rgb(26, 188, 156); | ||
| } | ||
|
|
||
| .admonition.important>.admonition-title { | ||
| color: rgb(26, 188, 156); | ||
| } |
Oops, something went wrong.