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.

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

gh-96265: Fix some formatting in faq/design.rst #96924

Merged
merged 8 commits into from
Oct 7, 2022
Merged

Conversation

slateny
Copy link
Contributor

@slateny slateny commented Sep 19, 2022

@bedevere-bot bedevere-bot added awaiting review docs Documentation in the Doc dir skip news labels Sep 19, 2022
Doc/faq/design.rst Outdated Show resolved Hide resolved
Doc/faq/design.rst Outdated Show resolved Hide resolved
@ezio-melotti ezio-melotti self-assigned this Sep 19, 2022
Doc/faq/design.rst Outdated Show resolved Hide resolved
Doc/faq/design.rst Outdated Show resolved Hide resolved
Doc/faq/design.rst Outdated Show resolved Hide resolved
Copy link
Member

@CAM-Gerlach CAM-Gerlach left a 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

@@ -62,7 +62,7 @@ and think it is a bug in Python. It's not. This has little to do with Python,
and much more to do with how the underlying platform handles floating-point
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
Copy link
Member

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?

Copy link
Member

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.

Copy link
Contributor Author

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.

Copy link
Member

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.

Doc/faq/design.rst Outdated Show resolved Hide resolved
Doc/faq/design.rst Outdated Show resolved Hide resolved
Doc/faq/design.rst Show resolved Hide resolved
Doc/faq/design.rst Outdated Show resolved Hide resolved
Copy link
Member

@ezio-melotti ezio-melotti left a 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.

Doc/faq/design.rst Outdated Show resolved Hide resolved
Doc/faq/design.rst Outdated Show resolved Hide resolved
@ambv ambv merged commit 3a7e955 into python:main 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
* 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
@CAM-Gerlach
Copy link
Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants