From 67bff6199ff7c8b080ce839d9d0e748b8d39b161 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Sat, 5 Sep 2020 23:55:06 +0200 Subject: [PATCH 1/3] Add a change fragment about issue #8783 / PR #8848 --- news/8783.doc | 1 + news/8848.doc | 1 + 2 files changed, 2 insertions(+) create mode 100644 news/8783.doc create mode 120000 news/8848.doc diff --git a/news/8783.doc b/news/8783.doc new file mode 100644 index 00000000000..6d2bb8762d4 --- /dev/null +++ b/news/8783.doc @@ -0,0 +1 @@ +Added initial UX feedback widgets to docs. diff --git a/news/8848.doc b/news/8848.doc new file mode 120000 index 00000000000..a318abd149b --- /dev/null +++ b/news/8848.doc @@ -0,0 +1 @@ +8783.doc \ No newline at end of file From 3301284810f905bdb25c67233952892f7852df2d Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Sat, 5 Sep 2020 21:01:37 +0200 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=9D=20Add=20initial=20sphinx=20ext?= =?UTF-8?q?=20for=20per-doc=20feedbacks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolves #8783 --- docs/docs_feedback_sphinxext.py | 165 ++++++++++++++++++++++++++++++++ docs/html/conf.py | 22 ++++- 2 files changed, 186 insertions(+), 1 deletion(-) create mode 100644 docs/docs_feedback_sphinxext.py diff --git a/docs/docs_feedback_sphinxext.py b/docs/docs_feedback_sphinxext.py new file mode 100644 index 00000000000..90f2ddd7498 --- /dev/null +++ b/docs/docs_feedback_sphinxext.py @@ -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 ', + 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', + } diff --git a/docs/html/conf.py b/docs/html/conf.py index a88ac33e2e4..b859e990202 100644 --- a/docs/html/conf.py +++ b/docs/html/conf.py @@ -31,10 +31,14 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # extensions = ['sphinx.ext.autodoc'] extensions = [ + # native: 'sphinx.ext.extlinks', - 'pip_sphinxext', 'sphinx.ext.intersphinx', + # third-party: 'sphinx_tabs.tabs', + # in-tree: + 'docs_feedback_sphinxext', + 'pip_sphinxext', ] # intersphinx @@ -308,3 +312,19 @@ def to_document_name(path, base_dir): ) man_pages.append((fname_base, outname, description, u'pip developers', 1)) + +# -- Options for docs_feedback_sphinxext -------------------------------------- + +# NOTE: Must be one of 'attention', 'caution', 'danger', 'error', 'hint', +# NOTE: 'important', 'note', 'tip', 'warning' or 'admonition'. +docs_feedback_admonition_type = 'important' +docs_feedback_big_doc_lines = 50 # bigger docs will have a banner on top +docs_feedback_email = 'Docs UX Team ' +docs_feedback_excluded_documents = { # these won't have any banners + 'news', +} +docs_feedback_questions_list = ( + 'What problem were you trying to solve when you came to this page?', + 'What content was useful?', + 'What content was not useful?', +) From 13962cd6adcf233c8e9b5a2875e706a19019cd24 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Sat, 5 Sep 2020 23:51:11 +0200 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=8E=A8=20Colorize=20the=20"important"?= =?UTF-8?q?=20admonition=20blocks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- MANIFEST.in | 2 +- docs/html/_static/important-admonition.css | 8 ++++++++ docs/html/conf.py | 2 +- 3 files changed, 10 insertions(+), 2 deletions(-) create mode 100644 docs/html/_static/important-admonition.css diff --git a/MANIFEST.in b/MANIFEST.in index aa6a1d0e71f..24d4553785b 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -22,7 +22,7 @@ exclude noxfile.py recursive-include src/pip/_vendor *.pem recursive-include src/pip/_vendor py.typed -recursive-include docs Makefile *.rst *.py *.bat +recursive-include docs *.css *.rst *.py exclude src/pip/_vendor/six exclude src/pip/_vendor/six/moves diff --git a/docs/html/_static/important-admonition.css b/docs/html/_static/important-admonition.css new file mode 100644 index 00000000000..a73ae2e4d4c --- /dev/null +++ b/docs/html/_static/important-admonition.css @@ -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); +} diff --git a/docs/html/conf.py b/docs/html/conf.py index b859e990202..444d15a819a 100644 --- a/docs/html/conf.py +++ b/docs/html/conf.py @@ -181,7 +181,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] +html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format.