Title: bpo-40204: Update documentation formatting for Sphinx 3.0 by jakobandersen · Pull Request #19397 · python/cpython · GitHub
Open Graph Title: bpo-40204: Update documentation formatting for Sphinx 3.0 by jakobandersen · Pull Request #19397 · python/cpython
X Title: bpo-40204: Update documentation formatting for Sphinx 3.0 by jakobandersen · Pull Request #19397 · python/cpython
Description: In the recently released Sphinx v3.0 the C domain has been rewritten to improve parsing of declarations and cross-referencing capabilities. However, this means that the existing directives has gotten more strict on the type of entities they accept. This PR updates the documentation to use the new directives and roles. Many of the changes are related to C constructs in running text where a type or expression is "referenced". These have been changed to use the new markup role c:expr which accepts arbitrary types or expressions. This is in opposition to the other roles, like c:type which is for cross-referencing a type declared with a directive. A few issues I couldn't immediately resovle: The refcount annotation in tools/extensions/c_annoations.py no longer works (though first broken in sphinx-doc/sphinx#7269). c-api/module.rst:194: the old m_reload is technically declared inside the scope of m_slots. This is now reflected in its ID/permalink. c-api/call.rst: The two functions PyObject_CallFunctionObjArgs and PyObject_CallMethodObjArgs takes a variable amount of arguments, though the last one must be NULL, indicated explicitly in the declaration. This is not valid C. There could be a configuration option in Sphinx to allow this. Please open an issue for Sphinx if you find this is relevant. howto/instrumentation.rst: The c:function directive is used for some markers, but without a return type. The type void was added. However, python.function.return contains return which is a C keyword, so a warning is generated. The elegant solution would perhaps be to code a custom domain for these things, as they are not really C declarations (as far as I understand). c-api/unicode.rst: The function PyUnicode_Translate is documented twice. c-api/init.rst: There are several instances mentioning "wchar_* string". Should this be :c:expr:`wchar_t*` string? https://bugs.python.org/issue40204
Open Graph Description: In the recently released Sphinx v3.0 the C domain has been rewritten to improve parsing of declarations and cross-referencing capabilities. However, this means that the existing directives has gott...
X Description: In the recently released Sphinx v3.0 the C domain has been rewritten to improve parsing of declarations and cross-referencing capabilities. However, this means that the existing directives has gott...
Opengraph URL: https://github.com/python/cpython/pull/19397
X: @github
Domain: github.com
| route-pattern | /:user_id/:repository/pull/:id/files(.:format) |
| route-controller | pull_requests |
| route-action | files |
| fetch-nonce | v2:637a9b7a-fceb-ff49-7114-74d197f84bb4 |
| current-catalog-service-hash | ae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b |
| request-id | D55E:E839C:6040C5:864517:696A78D5 |
| html-safe-nonce | a6bbb09b31a9e9cc79191ce9ac1ab4abffcb989786a304c25094a56816ac8178 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJENTVFOkU4MzlDOjYwNDBDNTo4NjQ1MTc6Njk2QTc4RDUiLCJ2aXNpdG9yX2lkIjoiMTUwNjEzNDI0Mzc5NDM4NTEwOSIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 86912668ea9f010507cd5a7c096c30d805baedb7cec4fb4c0e997b5920f151ec |
| hovercard-subject-tag | pull_request:399800349 |
| github-keyboard-shortcuts | repository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/python/cpython/pull/19397/files |
| twitter:image | https://avatars.githubusercontent.com/u/6465735?s=400&v=4 |
| twitter:card | summary_large_image |
| og:image | https://avatars.githubusercontent.com/u/6465735?s=400&v=4 |
| og:image:alt | In the recently released Sphinx v3.0 the C domain has been rewritten to improve parsing of declarations and cross-referencing capabilities. However, this means that the existing directives has gott... |
| og:site_name | GitHub |
| og:type | object |
| hostname | github.com |
| expected-hostname | github.com |
| None | 5b774e44f85c14a75886edd04ddda4e5a25ddebbb241bcbb590b08a3048730e8 |
| turbo-cache-control | no-preview |
| diff-view | unified |
| go-import | github.com/python/cpython git https://github.com/python/cpython.git |
| octolytics-dimension-user_id | 1525981 |
| octolytics-dimension-user_login | python |
| octolytics-dimension-repository_id | 81598961 |
| octolytics-dimension-repository_nwo | python/cpython |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 81598961 |
| octolytics-dimension-repository_network_root_nwo | python/cpython |
| turbo-body-classes | logged-out env-production page-responsive full-width |
| disable-turbo | true |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | cc5f4eee261b3601c1e98e217ceaf28508b9567e |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
Links:
Viewport: width=device-width