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.

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Jump to bottom

Improve faq/design.rst rst markup #96265

Closed
ezio-melotti opened this issue Aug 25, 2022 · 3 comments
Closed

Improve faq/design.rst rst markup #96265

ezio-melotti opened this issue Aug 25, 2022 · 3 comments
Assignees
@slateny
Labels
docs Documentation in the Doc dir

Comments

@ezio-melotti
Copy link
Member

ezio-melotti commented Aug 25, 2022 •
edited by bedevere-bot
Loading

I noticed that the faq/design.rst page has several parts that either have no markup (e.g. try/except, :=, etc.) or a generic ``...`` when a more specific one could be used (e.g. :c:type:`double`).

We should review the page and apply proper markup where applicable. Some other FAQs might need the same treatment.
@ezio-melotti ezio-melotti added the docs Documentation in the Doc dir label Aug 25, 2022
@bedevere-bot bedevere-bot mentioned this issue Sep 19, 2022
Merged
@slateny
Copy link
Contributor

slateny commented Sep 19, 2022

Created a PR for just design.rst - as for other FAQs, I think the general faq could get some grave accents too (maybe under 'version numbering', A.B.C etc. could be literal), but changes to design.rst are looking somewhat long already so I'll put them in a separate PR.

Some of the missing formatting can also be found in other docs (i.e., ``if`` -> :keyword:`if`), should those be globally applied or should it change file-by-file?

@CAM-Gerlach
Copy link
Member

File by file, I'd say, if we're going through them, unless that's the only change needed in the file

@CAM-Gerlach CAM-Gerlach mentioned this issue Sep 22, 2022
Merged
ambv pushed a commit that referenced this issue Oct 7, 2022
@slateny @ezio-melotti @CAM-Gerlach
gh-96265: Fix some formatting in faq/design.rst (#96924)
3a7e955 
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
carljm added a commit to carljm/cpython that referenced this issue Oct 8, 2022
@carljm
Merge branch 'main' into typewatch
27a4980 
* main: (38 commits)
  pythongh-92886: make test_ast pass with -O (assertions off) (pythonGH-98058)
  pythongh-92886: make test_coroutines pass with -O (assertions off) (pythonGH-98060)
  pythongh-57179: Add note on symlinks for os.walk (python#94799)
  pythongh-94808: Fix regex on exotic platforms (python#98036)
  pythongh-90085: Remove vestigial -t and -c timeit options (python#94941)
  pythonGH-83901: Improve Signature.bind error message for missing keyword-only params (python#95347)
  pythongh-61105: Add default param, note on using cookiejar subclass (python#95427)
  pythongh-96288: Add a sentence to `os.mkdir`'s docstring. (python#96271)
  pythongh-96073: fix backticks in NEWS entry (pythonGH-98056)
  pythongh-92886: [clinic.py] raise exception on invalid input instead of assertion (pythonGH-98051)
  pythongh-97997: Add col_offset field to tokenizer and use that for AST nodes (python#98000)
  pythonGH-88968: Reject socket that is already used as a transport (python#98010)
  pythongh-96346: Use double caching for re._compile() (python#96347)
  pythongh-91708: Revert params note in urllib.parse.urlparse table (python#96699)
  pythongh-96265: Fix some formatting in faq/design.rst (python#96924)
  pythongh-73196: Add namespace/scope clarification for inheritance section (python#92840)
  pythongh-97646: Change `.js` and `.mjs` files mimetype to conform to RFC 9239 (python#97934)
  pythongh-97923: Always run Ubuntu SSL tests with others in CI (python#97940)
  pythongh-97956: Mention `generate_global_objects.py` in `AC How-To` (python#97957)
  pythongh-96959: Update HTTP links which are redirected to HTTPS (python#98039)
  ...
@bedevere-bot bedevere-bot mentioned this issue Oct 9, 2022
Merged
mpage pushed a commit to mpage/cpython that referenced this issue Oct 11, 2022
@slateny @ezio-melotti
@CAM-Gerlach @mpage
pythongh-96265: Fix some formatting in faq/design.rst (python#96924)
53bc2db 
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
ezio-melotti added a commit that referenced this issue Oct 12, 2022
@slateny @ezio-melotti @CAM-Gerlach
gh-96265: Formatting changes for faq/general (#98129)
e9569ec 
* Some formatting changes for general faq

* Use list for Python versioning

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>

* New line for list, list for a/b/rc

* Line wrap for 80 chars

* More line wrap

* Remove PythonWin mention.

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Oct 12, 2022
@slateny @miss-islington
pythongh-96265: Formatting changes for faq/general (pythonGH-98129)
d3b86f8 
* Some formatting changes for general faq

* Use list for Python versioning

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>

* New line for list, list for a/b/rc

* Line wrap for 80 chars

* More line wrap

* Remove PythonWin mention.

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit e9569ec)

Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
@bedevere-bot bedevere-bot mentioned this issue Oct 12, 2022
Merged
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Oct 12, 2022
@slateny @miss-islington
pythongh-96265: Formatting changes for faq/general (pythonGH-98129)
0ba2196 
* Some formatting changes for general faq

* Use list for Python versioning

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>

* New line for list, list for a/b/rc

* Line wrap for 80 chars

* More line wrap

* Remove PythonWin mention.

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit e9569ec)

Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
@bedevere-bot bedevere-bot mentioned this issue Oct 12, 2022
Merged
miss-islington added a commit that referenced this issue Oct 12, 2022
@miss-islington @slateny
gh-96265: Formatting changes for faq/general (GH-98129)
258c440 
* Some formatting changes for general faq

* Use list for Python versioning

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>

* New line for list, list for a/b/rc

* Line wrap for 80 chars

* More line wrap

* Remove PythonWin mention.

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit e9569ec)

Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
miss-islington added a commit that referenced this issue Oct 12, 2022
@miss-islington @slateny
gh-96265: Formatting changes for faq/general (GH-98129)
450306e 
* Some formatting changes for general faq

* Use list for Python versioning

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>

* New line for list, list for a/b/rc

* Line wrap for 80 chars

* More line wrap

* Remove PythonWin mention.

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit e9569ec)

Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
@bedevere-bot bedevere-bot mentioned this issue Oct 13, 2022
Merged
carljm added a commit to carljm/cpython that referenced this issue Oct 14, 2022
@carljm
Merge branch 'main' into typewatch
6e53514 
* main: (38 commits)
  pythongh-98251: Allow venv to pass along PYTHON* variables to pip and ensurepip when they do not impact path resolution (pythonGH-98259)
  Bpo-41246: IOCP Proactor avoid callback code duplication (python#21399)
  bpo-46364: Use sockets for stdin of asyncio only on AIX (python#30596)
  pythongh-98178: syslog() is not thread-safe on macOS (python#98213)
  Mark all targets in `Doc/Makefile` as `PHONY` (pythonGH-98189)
  pythongh-97982: Factorize PyUnicode_Count() and unicode_count() code (python#98025)
  pythongh-96265: Formatting changes for faq/general (python#98129)
  tutorial: remove "with single quotes" (python#98204)
  pythongh-97669: Remove Tools/scripts/startuptime.py (python#98214)
  signalmodule.c uses _PyErr_WriteUnraisableMsg() (python#98217)
  pythongh-97669: Fix test_tools reference leak (python#98216)
  pythongh-97669: Create Tools/patchcheck/ directory (python#98186)
  pythongh-65046: Link to logging cookbook from asyncio docs (python#98207)
  Formatting fixes in contextlib docs (python#98111)
  pythongh-95276: Add callable entry to the glossary (python#95738)
  pythongh-96130: Rephrase use of "typecheck" verb for clarity (python#98144)
  Fix some incorrect indentation around the main switch (python#98177)
  pythongh-98172: Fix formatting in `except*` docs (python#98173)
  pythongh-97982: Remove asciilib_count() (python#98164)
  pythongh-95756: Free and NULL-out code caches when needed (pythonGH-98181)
  ...
carljm added a commit to carljm/cpython that referenced this issue Oct 14, 2022
@carljm
Merge branch 'main' into cached_property
0bb0c69 
* main: (37 commits)
  pythongh-98251: Allow venv to pass along PYTHON* variables to pip and ensurepip when they do not impact path resolution (pythonGH-98259)
  Bpo-41246: IOCP Proactor avoid callback code duplication (python#21399)
  bpo-46364: Use sockets for stdin of asyncio only on AIX (python#30596)
  pythongh-98178: syslog() is not thread-safe on macOS (python#98213)
  Mark all targets in `Doc/Makefile` as `PHONY` (pythonGH-98189)
  pythongh-97982: Factorize PyUnicode_Count() and unicode_count() code (python#98025)
  pythongh-96265: Formatting changes for faq/general (python#98129)
  tutorial: remove "with single quotes" (python#98204)
  pythongh-97669: Remove Tools/scripts/startuptime.py (python#98214)
  signalmodule.c uses _PyErr_WriteUnraisableMsg() (python#98217)
  pythongh-97669: Fix test_tools reference leak (python#98216)
  pythongh-97669: Create Tools/patchcheck/ directory (python#98186)
  pythongh-65046: Link to logging cookbook from asyncio docs (python#98207)
  Formatting fixes in contextlib docs (python#98111)
  pythongh-95276: Add callable entry to the glossary (python#95738)
  pythongh-96130: Rephrase use of "typecheck" verb for clarity (python#98144)
  Fix some incorrect indentation around the main switch (python#98177)
  pythongh-98172: Fix formatting in `except*` docs (python#98173)
  pythongh-97982: Remove asciilib_count() (python#98164)
  pythongh-95756: Free and NULL-out code caches when needed (pythonGH-98181)
  ...
@CAM-Gerlach CAM-Gerlach mentioned this issue Oct 21, 2022
Merged
pablogsal pushed a commit that referenced this issue Oct 22, 2022
@miss-islington @slateny @pablogsal
gh-96265: Formatting changes for faq/general (GH-98129)
0f3c5ab 
* Some formatting changes for general faq

* Use list for Python versioning

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>

* New line for list, list for a/b/rc

* Line wrap for 80 chars

* More line wrap

* Remove PythonWin mention.

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit e9569ec)

Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
ezio-melotti pushed a commit that referenced this issue Nov 2, 2022
@slateny @CAM-Gerlach
gh-96265: Formatting changes for faq/programming (#98242)
0689b99 
* Formatting changes for faq/programming

* Add missing method formatting, use non-literal formatting

* Fix sphinx warnings

* Some extra formatting missed earlier

* More formatting suggestions from review

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

* Add missing colon, avoid referening external module

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@bedevere-bot bedevere-bot mentioned this issue Nov 2, 2022
Merged
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Nov 2, 2022
@slateny @CAM-Gerlach @miss-islington
pythongh-96265: Formatting changes for faq/programming (pythonGH-98242)
4a30220 
* Formatting changes for faq/programming

* Add missing method formatting, use non-literal formatting

* Fix sphinx warnings

* Some extra formatting missed earlier

* More formatting suggestions from review

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

* Add missing colon, avoid referening external module

(cherry picked from commit 0689b99)

Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
miss-islington added a commit that referenced this issue Nov 2, 2022
@miss-islington @slateny @CAM-Gerlach
gh-96265: Formatting changes for faq/programming (GH-98242)
d683bcc 
* Formatting changes for faq/programming

* Add missing method formatting, use non-literal formatting

* Fix sphinx warnings

* Some extra formatting missed earlier

* More formatting suggestions from review

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

* Add missing colon, avoid referening external module

(cherry picked from commit 0689b99)

Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
slateny added a commit to slateny/cpython that referenced this issue Nov 2, 2022
@slateny
[3.10] pythongh-96265: Formatting changes for faq/programming (python…
28567d0 
…GH-98242)

* Formatting changes for faq/programming

* Add missing method formatting, use non-literal formatting

* Fix sphinx warnings

* Some extra formatting missed earlier

* More formatting suggestions from review

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

* Add missing colon, avoid referening external module

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>.
(cherry picked from commit 0689b99)

Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
@bedevere-bot bedevere-bot mentioned this issue Nov 2, 2022
Merged
ezio-melotti pushed a commit that referenced this issue Nov 3, 2022
@slateny
[3.10] gh-96265: Formatting changes for faq/programming (GH-98242) (#…
c592b33 
…98994)

* Formatting changes for faq/programming

* Add missing method formatting, use non-literal formatting

* Fix sphinx warnings

* Some extra formatting missed earlier

* More formatting suggestions from review

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

* Add missing colon, avoid referening external module

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>.
(cherry picked from commit 0689b99)

Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
@hauntsaninja
Copy link
Contributor

Thanks, closing. We can open another issue for any other FAQs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@slateny slateny

Labels
docs Documentation in the Doc dir
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@hauntsaninja @CAM-Gerlach @ezio-melotti @slateny