You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@iceberg.apache.org by "rodrigc (via GitHub)" <gi...@apache.org> on 2025/01/16 22:40:00 UTC
[I] Typedefs such as Identifier, Properties, and RecursiveDict are not hyperlinked in the generated documentation [iceberg-python]
rodrigc opened a new issue, #1529:
URL: https://github.com/apache/iceberg-python/issues/1529
### Apache Iceberg version
0.8.1 (latest release)
### Please describe the bug 🐞
I was working on writing some code with pyiceberg, and I noticed that
[Identifier](https://github.com/apache/iceberg-python/blob/e8e2c91379b4b4eb501b7b60355837af73c7c35e/pyiceberg/typedef.py#L76) is not hyperlinked in the docs.
For example here:
https://py.iceberg.apache.org/reference/pyiceberg/catalog/#pyiceberg.catalog.Catalog.create_table_if_not_exists
It would be useful to get types that are defined in the Pyiceberg library to be hyperlinked in the documentation.
This would also apply for types such as [Properties
(https://github.com/apache/iceberg-python/blob/e8e2c91379b4b4eb501b7b60355837af73c7c35e/pyiceberg/typedef.py#L77) and [RecursiveDict](https://github.com/apache/iceberg-python/blob/e8e2c91379b4b4eb501b7b60355837af73c7c35e/pyiceberg/typedef.py#L78).
### Willingness to contribute
- [ ] I can contribute a fix for this bug independently
- [x] I would be willing to contribute a fix for this bug with guidance from the Iceberg community
- [ ] I cannot contribute a fix for this bug at this time
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [I] Typedefs such as Identifier, Properties, and RecursiveDict are not hyperlinked in the generated documentation [iceberg-python]
Posted by "Fokko (via GitHub)" <gi...@apache.org>.
Fokko closed issue #1529: Typedefs such as Identifier, Properties, and RecursiveDict are not hyperlinked in the generated documentation
URL: https://github.com/apache/iceberg-python/issues/1529
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [I] Typedefs such as Identifier, Properties, and RecursiveDict are not hyperlinked in the generated documentation [iceberg-python]
Posted by "Fokko (via GitHub)" <gi...@apache.org>.
Fokko closed issue #1529: Typedefs such as Identifier, Properties, and RecursiveDict are not hyperlinked in the generated documentation
URL: https://github.com/apache/iceberg-python/issues/1529
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [I] Typedefs such as Identifier, Properties, and RecursiveDict are not hyperlinked in the generated documentation [iceberg-python]
Posted by "rodrigc (via GitHub)" <gi...@apache.org>.
rodrigc commented on issue #1529:
URL: https://github.com/apache/iceberg-python/issues/1529#issuecomment-2597129840
Your advice led me down the correct path to identify the problem.
mkdocstrings relies on the presence of docstrings to recognize and document variables, types, and other attributes. Since those types did not have docstrings, they were not picked up by mkdocstrings.
I submitted this PR: https://github.com/apache/iceberg-python/pull/1530
and when I ran `make docs-serve` locally, I could now see that `Identifier` was hyperlinked in the docs for
`create_table_if_not_exists()`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [I] Typedefs such as Identifier, Properties, and RecursiveDict are not hyperlinked in the generated documentation [iceberg-python]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu commented on issue #1529:
URL: https://github.com/apache/iceberg-python/issues/1529#issuecomment-2597063631
BTW you can run a local version of the docs website by running `make docs-serve`. Hope this helps! And happy to answer any follow up questions
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [I] Typedefs such as Identifier, Properties, and RecursiveDict are not hyperlinked in the generated documentation [iceberg-python]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu commented on issue #1529:
URL: https://github.com/apache/iceberg-python/issues/1529#issuecomment-2597061263
Thanks for reporting this! Its helpful to have those variables available and linked in the docs.
For context, we use `mkdocstrings` to generate docs from the source code. I think the current problem is that variables such as `Identifier` , `Properties` and `RecursiveDict` are [not recognized in the docs under typedef](https://py.iceberg.apache.org/reference/pyiceberg/typedef/). And because its not recognized, the rest of the docs are not able to hyperlink to it.
A potential solution is to add docstring to the variables. The docstrings should force `mkdocstrings` to recognize these as part of the docs.
from https://mkdocstrings.github.io/python/#features:
> Support for documented attributes: attributes (variables) followed by a docstring (triple-quoted string) will be recognized by Griffe in modules, classes and even in __init__ methods.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [I] Typedefs such as Identifier, Properties, and RecursiveDict are not hyperlinked in the generated documentation [iceberg-python]
Posted by "rodrigc (via GitHub)" <gi...@apache.org>.
rodrigc commented on issue #1529:
URL: https://github.com/apache/iceberg-python/issues/1529#issuecomment-2597100519
The docs are generated via the scripts here: https://github.com/apache/iceberg-python/tree/main/mkdocs
I did the following:
1. Put debugging in https://github.com/apache/iceberg-python/blob/main/mkdocs/gen_doc_stubs.py to see what files are being parsed
2. Ran:
```
make docs-install
make docs-serve
```
I observed that https://github.com/apache/iceberg-python/tree/main/pyiceberg/typedef.py is not parsed.
https://github.com/apache/iceberg-python/tree/main/pyiceberg/__init__.py, and a lot of other files *are* parsed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org