You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by GitBox <gi...@apache.org> on 2020/10/11 21:46:08 UTC
[GitHub] [airflow] kaxil opened a new pull request #11446: Use Sphinx Auto Typehints for docstrings
kaxil opened a new pull request #11446:
URL: https://github.com/apache/airflow/pull/11446
https://pypi.org/project/sphinx-autodoc-typehints/
This extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types of functions. This allows you to use type hints in a very natural fashion, allowing you to migrate from this:
```
def format_unit(value, unit):
"""
Formats the given value as a human readable string using the given units.
:param float|int value: a numeric value
:param str unit: the unit for the value (kg, m, etc.)
:rtype: str
"""
return '{} {}'.format(value, unit)
```
to
```
from typing import Union
def format_unit(value: Union[float, int], unit: str) -> str:
"""
Formats the given value as a human readable string using the given units.
:param value: a numeric value
:param unit: the unit for the value (kg, m, etc.)
"""
return '{} {}'.format(value, unit)
```
<!--
Thank you for contributing! Please make sure that your code changes
are covered with tests. And in case of new features or big changes
remember to adjust the documentation.
Feel free to ping committers for the review!
In case of existing issue, reference it using one of the following:
closes: #ISSUE
related: #ISSUE
How to write a good git commit message:
http://chris.beams.io/posts/git-commit/
-->
---
**^ Add meaningful description above**
Read the **[Pull Request Guidelines](https://github.com/apache/airflow/blob/master/CONTRIBUTING.rst#pull-request-guidelines)** for more information.
In case of fundamental code change, Airflow Improvement Proposal ([AIP](https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvements+Proposals)) is needed.
In case of a new dependency, check compliance with the [ASF 3rd Party License Policy](https://www.apache.org/legal/resolved.html#category-x).
In case of backwards incompatible changes please leave a note in [UPDATING.md](https://github.com/apache/airflow/blob/master/UPDATING.md).
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [airflow] mik-laj commented on pull request #11446: Use Sphinx Auto Typehints for docstrings
Posted by GitBox <gi...@apache.org>.
mik-laj commented on pull request #11446:
URL: https://github.com/apache/airflow/pull/11446#issuecomment-706772997
Is it compatibile with sphinx-autoapi?
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [airflow] kaxil commented on pull request #11446: Use Sphinx Auto Typehints for docstrings
Posted by GitBox <gi...@apache.org>.
kaxil commented on pull request #11446:
URL: https://github.com/apache/airflow/pull/11446#issuecomment-706773823
> Is it compatibile with sphinx-autoapi?
I think so, have seen few projects use it: https://github.com/asappresearch/flambe/blob/38e92673d00550e5f6292330f7dda899b2bf581c/docs/requirements.txt
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [airflow] github-actions[bot] commented on pull request #11446: Use Sphinx Auto Typehints for docstrings
Posted by GitBox <gi...@apache.org>.
github-actions[bot] commented on pull request #11446:
URL: https://github.com/apache/airflow/pull/11446#issuecomment-706778090
[The Workflow run](https://github.com/apache/airflow/actions/runs/301022270) is cancelling this PR. Building images for the PR has failed. Follow the the workflow link to check the reason.
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [airflow] kaxil commented on pull request #11446: Use Sphinx Auto Typehints for docstrings
Posted by GitBox <gi...@apache.org>.
kaxil commented on pull request #11446:
URL: https://github.com/apache/airflow/pull/11446#issuecomment-707147616
> It still doesn't work.
> Before:
> <img alt="Screenshot 2020-10-12 at 13 24 21" width="784" src="https://user-images.githubusercontent.com/12058428/95746261-cd10f380-0c96-11eb-8b08-6d2af91260dc.png">
> After:
> <img alt="Screenshot 2020-10-12 at 14 24 42" width="843" src="https://user-images.githubusercontent.com/12058428/95746284-d4d09800-0c96-11eb-915e-a0c0659a839e.png">
>
> This only adds types on one page - https://airflow.readthedocs.io/en/latest/macros-ref.html#airflow.macros.datetime_diff_for_humans. We use `.. automodule:: `and `.. autofunction:: `, but these functions don't have type hints, so it's not very useful in our project.
gaah :( Sad
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [airflow] mik-laj commented on pull request #11446: Use Sphinx Auto Typehints for docstrings
Posted by GitBox <gi...@apache.org>.
mik-laj commented on pull request #11446:
URL: https://github.com/apache/airflow/pull/11446#issuecomment-707089959
It still doesn't work.
Before:
<img width="784" alt="Screenshot 2020-10-12 at 13 24 21" src="https://user-images.githubusercontent.com/12058428/95746261-cd10f380-0c96-11eb-8b08-6d2af91260dc.png">
After:
<img width="843" alt="Screenshot 2020-10-12 at 14 24 42" src="https://user-images.githubusercontent.com/12058428/95746284-d4d09800-0c96-11eb-915e-a0c0659a839e.png">
This only adds types on one page - https://airflow.readthedocs.io/en/latest/macros-ref.html#airflow.macros.datetime_diff_for_humans. We use `.. automodule:: `and `.. autofunction:: `, but these functions don't have type hints, so it's not very useful in our project.
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [airflow] mik-laj commented on pull request #11446: Use Sphinx Auto Typehints for docstrings
Posted by GitBox <gi...@apache.org>.
mik-laj commented on pull request #11446:
URL: https://github.com/apache/airflow/pull/11446#issuecomment-706956189
@kaxil I'll check it out. It used to be incompatible, ie sphinx-auto-typehint only worked properly on pages that do not use sphinx-autoapi.
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [airflow] github-actions[bot] commented on pull request #11446: Use Sphinx Auto Typehints for docstrings
Posted by GitBox <gi...@apache.org>.
github-actions[bot] commented on pull request #11446:
URL: https://github.com/apache/airflow/pull/11446#issuecomment-706785199
[The Workflow run](https://github.com/apache/airflow/actions/runs/301070948) is cancelling this PR. Building images for the PR has failed. Follow the the workflow link to check the reason.
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [airflow] kaxil closed pull request #11446: Use Sphinx Auto Typehints for docstrings
Posted by GitBox <gi...@apache.org>.
kaxil closed pull request #11446:
URL: https://github.com/apache/airflow/pull/11446
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org