GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-96265: Fix some formatting in faq/design.rst by slateny · Pull Request #96924 · python/cpython

Conversation

@slateny

@slateny slateny commented Sep 19, 2022 •
edited by bedevere-bot
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

https://docs.python.org/dev/faq/design.html

  • Issue: Improve faq/design.rst rst markup #96265

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@slateny
Fix some formatting in faq/design.rst
c085851
@bedevere-bot bedevere-bot added awaiting review docs Documentation in the Doc dir skip news labels Sep 19, 2022
slateny
slateny commented Sep 19, 2022
View reviewed changes
Comment thread Doc/faq/design.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/faq/design.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@ezio-melotti ezio-melotti self-assigned this Sep 19, 2022
ezio-melotti
ezio-melotti reviewed Sep 19, 2022
View reviewed changes
Comment thread Doc/faq/design.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/faq/design.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/faq/design.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@ezio-melotti
ezio-melotti requested a review from CAM-Gerlach September 19, 2022 08:16
slateny and others added 2 commits September 19, 2022 02:50
@slateny
Use links instead of literal
c300f88
@slateny @ezio-melotti
Add back quotes
a96893a 
Co-authored-by: Ezio Melotti <[email protected]>
CAM-Gerlach
CAM-Gerlach reviewed Sep 19, 2022
View reviewed changes

@CAM-Gerlach CAM-Gerlach left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

By the way, this is a great example of what Diataxis calls an Explanation.

While you're at it, some existing ref targets are broken that you might want to fix, which look to be due to being annotated as methods, but the class (e.g. object or list) is not included. If you change them from e.g. :meth:`__init__` to :meth:`~object.__init__` they should display the same, but resolve correctly.

List of broken ref targets 
C:\Users\C. A. M. Gerlach\Documents\dev\Python\cpython\test\Doc\faq\design.rst:127: WARNING: py:meth reference target not found: __init__
C:\Users\C. A. M. Gerlach\Documents\dev\Python\cpython\test\Doc\faq\design.rst:498: WARNING: py:meth reference target not found: __eq__
C:\Users\C. A. M. Gerlach\Documents\dev\Python\cpython\test\Doc\faq\design.rst:498: WARNING: py:meth reference target not found: __hash__
C:\Users\C. A. M. Gerlach\Documents\dev\Python\cpython\test\Doc\faq\design.rst:581: WARNING: py:meth reference target not found: append
C:\Users\C. A. M. Gerlach\Documents\dev\Python\cpython\test\Doc\faq\design.rst:581: WARNING: py:meth reference target not found: append

Somewhat related: #95976

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
slateny and ezio-melotti reacted with thumbs up emoji
All reactions
  • 👍 2 reactions
Comment thread Doc/faq/design.rst
numbers.

The :class:`float` type in CPython uses a C ``double`` for storage. A
The :class:`float` type in CPython uses a C :c:type:`double` for storage. A

@CAM-Gerlach CAM-Gerlach Sep 19, 2022

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

There's no double type defined in Python's documentation (since its defined in the C standard) or auto-linked/formatted by Sphinx and this apparently isn't given any special formatting by the current Python docs theme. Maybe this should be rolled back, or we should fix the theme to format C-domain types correctly? Or perhaps this has something to do with enabling the legacy C domain syntax mode in conf.py that @AA-Turner 's been working on getting rid of the need for?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@CAM-Gerlach CAM-Gerlach Sep 19, 2022

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

If I recall, I believe that regular literals (double backticks) are how you've handled this sort of thing elsewhere.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@slateny slateny Sep 20, 2022

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Doing a quick search through the repo I'm seeing more (23 vs 5) in the form of :c:type:`double`, so keeping it would be more in line with what's currently being done.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@CAM-Gerlach CAM-Gerlach Sep 22, 2022

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Okay, I see. Still, it is strange that it is formatted as prose rather than as a literal, as we'd (and I assume the original authors) would expect—perhaps something changed in the theme, Sphinx or the configuration that resulted in that not happening as expected.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/faq/design.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/faq/design.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/faq/design.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/faq/design.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
slateny added 2 commits September 20, 2022 23:07
@slateny
Add more proper refs
a7542ba
@slateny
Add formatting for walrus operator
2d68707
ezio-melotti
ezio-melotti approved these changes Sep 21, 2022
View reviewed changes

@ezio-melotti ezio-melotti left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Two minor nits, otherwise LGTM.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/faq/design.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/faq/design.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-bot bedevere-bot added awaiting merge and removed awaiting review labels Sep 21, 2022
slateny and others added 3 commits September 22, 2022 02:10
@slateny
Use list.append instead of append, if-else -> if/else
399564c
@slateny @ezio-melotti
Wrap long line
e110dd1 
Co-authored-by: Ezio Melotti <[email protected]>
@slateny @CAM-Gerlach
Remove literal from big-O
ce33989 
Co-authored-by: C.A.M. Gerlach <[email protected]>
@ambv
ambv merged commit 3a7e955 into python:main Oct 7, 2022
@bedevere-bot bedevere-bot removed the awaiting merge label Oct 7, 2022
@slateny
slateny deleted the s/96265 branch October 8, 2022 15:22
carljm added a commit to carljm/cpython that referenced this pull request 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)
  ...
mpage pushed a commit to mpage/cpython that referenced this pull request 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 <[email protected]>
Co-authored-by: C.A.M. Gerlach <[email protected]>
@CAM-Gerlach

CAM-Gerlach commented Oct 16, 2022

Copy link
Copy Markdown
Member

Hey @ezio-melotti is there a reason this one wasn't backported (but the other ones were?)
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@CAM-Gerlach CAM-Gerlach CAM-Gerlach left review comments
@ezio-melotti ezio-melotti ezio-melotti approved these changes

Uh oh!

There was an error while loading. Please reload this page.

Assignees

@ezio-melotti ezio-melotti

Labels

docs Documentation in the Doc dir skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

5 participants

@slateny @CAM-Gerlach @ezio-melotti @ambv @bedevere-bot
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.