gh-96265: Fix some formatting in faq/design.rst #96924
Conversation
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
There was a problem hiding this comment.
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 | |||
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
If I recall, I believe that regular literals (double backticks) are how you've handled this sort of thing elsewhere.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
* 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) ...
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
|
Hey @ezio-melotti is there a reason this one wasn't backported (but the other ones were?) |
https://docs.python.org/dev/faq/design.html
faq/design.rstrst markup #96265