DOC: Add py:type reference targets to pandas.api.typing.aliases #63812
Conversation
Removed outdated documentation section and fixed broken Sphinx reference targets.
Added a warning not to use a specific section in the documentation.
Co-authored-by: Philipp A. <[email protected]>
|
/preview |
|
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/63812/ |
|
So if you look at the preview at https://pandas.pydata.org/preview/pandas-dev/pandas/63812/docs/reference/aliases.html#module-pandas.api.typing.aliases and the published version at https://pandas.pydata.org/docs/dev/reference/aliases.html you'll see that the changes have lost the aspect of this being in a table. I don't know if there is a way to preserve that. Can you find out? |
|
Maybe possible with list tables? https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table |
|
/preview |
|
What are you doing? As said, |
|
oh bro why your sheeps eyes are looking red now |
|
Lol, I’ve just spent wayy too much time debugging Sphinx docs. I’m usually not sad, I just just know that I'm often the only guy around who knows how everything works together. That's why I sometimes just say “do this thing”: because I know it's the only thing that makes sense. |
|
@flying-sheep There is 2:00 am here i forget to see time 😅 |
Updated the typing aliases documentation to include a list table format for better readability and added descriptions for each alias.
|
Why do you keep removing Is that some kind of joke or are you trying to do something specific? Because if you're trying to do something then ask and I can help. I assure you that deleting |
|
@flying-sheep bro I applied you table logic and forget to change the module |
Removed multiple argument type definitions for various methods and added a duplicate entry for XMLParsers.
|
/preview |
|
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/63812/ |
|
@flying-sheep after reading your table docs content i knew that sphinx is so strict with reStructuredText so i reStructured some texts to see if that works |
doc/source/reference/aliases.rst
Outdated
| .. list-table:: | ||
| :widths: 30 70 | ||
| :header-rows: 1 |
There was a problem hiding this comment.
Why can't we continue to use the markdown table with ===== as we do through most of the pandas docs?
There was a problem hiding this comment.
I didn't check but as said multiple times, rST has a lot of implicit rules about where it accepts inline syntax, block syntax, both, or neither.
I assume table syntax might only support inline syntax and not block syntax, and directives are block syntax.
But as said, that's only an assumption based on the PR author not using table syntax.
doc/source/reference/aliases.rst
Outdated
| * - Alias | ||
| - Meaning | ||
| * - | ||
| .. py:type:: AggFuncType |
There was a problem hiding this comment.
When this is rendered it looks like:
type pandas.api.typing.aliases.AggFuncType
The module pandas.api.typing.aliases is quite redundant for every entry. Is there a way that could be removed?
There was a problem hiding this comment.
ok thanks for clarification i think two backtick method will work by changing the module back to current module
There was a problem hiding this comment.
No, double backticks mean “this is code”. There point of this PR is to create reference targets.
In reference roles, using ~ will leave out the redundant part, but I'm not sure if it's possible to shorten here.
|
/preview |
|
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/63812/ |
|
/preview |
|
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/63812/ |
|
/preview |
|
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/63812/ |
|
@Dr-Irv is that good now ? |
|
@Dr-Irv @flying-sheep any difficulty to review this? |
|
/preview |
|
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/63812/ |
Dr-Irv
left a comment
Dr-Irv
left a comment
There was a problem hiding this comment.
the imports only work from pandas.api.typing.aliases
Co-authored-by: Irv Lustig <[email protected]>
Co-authored-by: Irv Lustig <[email protected]>
There was a problem hiding this comment.
I have no clue why you keep breaking this. It must be this:
.. module:: pandas.api.typing.aliases
and the table needs to look like this
==================================== ================================================================
Alias Meaning
==================================== ================================================================
.. type:: AggFuncType Type of functions that can be passed to :meth:`agg` methods
.. type:: AlignJoin Argument type for ``join`` in :meth:`DataFrame.join`
just do both of these things and the PR actually does what it says.
|
Thanks for the suggestion! @flying-sheep However, Dr-Irv explicitly requested to avoid using directives inside the table to ensure the layout remains stable and readable. I am sticking to the standard backticks approach becsuse In reStructuredText, "Simple Tables" (the ones with ====) are designed for simple text. You generally cannot put block-level directives (like .. type::) inside them reliably. It usually breaks the table structure or renders literally as text .. type:: . |
Irrelevant, there is no other way to create link targets. If you want things shorter @Dr-Irv, create a feature request in Sphinx. We could maybe also add a raw HTML block to that page reducing the font size in that table. But we use
Wrong, there is no problem. The simple table spec even recommends using comments (which are block-level syntax) if you want to keep the first cell empty, so it’s very much supported. |
3 participants
doc/source/whatsnew/vX.X.X.rstfile if fixing a bug or adding a new feature.AGENTS.md.This PR fixes the type aliases documentation to use proper Sphinx directives instead of references.
Changes
:py:type:references with.. py:type::directives