Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: fix GL08 errors in docstrings #57443

Closed
jordan-d-murphy opened this issue Feb 15, 2024 · 18 comments
Closed

DOC: fix GL08 errors in docstrings #57443

jordan-d-murphy opened this issue Feb 15, 2024 · 18 comments
Labels
CI Continuous Integration Docs good first issue

Comments

@jordan-d-murphy
Copy link
Contributor

Pandas has a script for validating docstrings:

pandas/ci/code_checks.sh

Lines 144 to 415 in 92a52e2

MSG='Partially validate docstrings (GL08)' ; echo $MSG
$BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=GL08 --ignore_functions \
pandas.DatetimeIndex.as_unit\
pandas.DatetimeIndex.freq\
pandas.ExcelFile.book\
pandas.ExcelFile.sheet_names\
pandas.Index.empty\
pandas.Index.names\
pandas.Index.view\
pandas.IntervalIndex.left\
pandas.IntervalIndex.length\
pandas.IntervalIndex.mid\
pandas.IntervalIndex.right\
pandas.MultiIndex.codes\
pandas.Period.freq\
pandas.Period.ordinal\
pandas.PeriodIndex.freq\
pandas.PeriodIndex.qyear\
pandas.Series.dt\
pandas.Series.dt.as_unit\
pandas.Series.dt.freq\
pandas.Series.dt.qyear\
pandas.Series.dt.unit\
pandas.Series.empty\
pandas.Timedelta.microseconds\
pandas.Timedelta.unit\
pandas.Timedelta.value\
pandas.Timestamp.day\
pandas.Timestamp.fold\
pandas.Timestamp.hour\
pandas.Timestamp.microsecond\
pandas.Timestamp.minute\
pandas.Timestamp.month\
pandas.Timestamp.nanosecond\
pandas.Timestamp.second\
pandas.Timestamp.tzinfo\
pandas.Timestamp.value\
pandas.Timestamp.year\
pandas.core.groupby.SeriesGroupBy.value_counts\
pandas.tseries.offsets.BQuarterBegin.is_anchored\
pandas.tseries.offsets.BQuarterBegin.is_on_offset\
pandas.tseries.offsets.BQuarterBegin.n\
pandas.tseries.offsets.BQuarterBegin.nanos\
pandas.tseries.offsets.BQuarterBegin.normalize\
pandas.tseries.offsets.BQuarterBegin.rule_code\
pandas.tseries.offsets.BQuarterBegin.startingMonth\
pandas.tseries.offsets.BQuarterEnd.is_anchored\
pandas.tseries.offsets.BQuarterEnd.is_on_offset\
pandas.tseries.offsets.BQuarterEnd.n\
pandas.tseries.offsets.BQuarterEnd.nanos\
pandas.tseries.offsets.BQuarterEnd.normalize\
pandas.tseries.offsets.BQuarterEnd.rule_code\
pandas.tseries.offsets.BQuarterEnd.startingMonth\
pandas.tseries.offsets.BYearBegin.is_on_offset\
pandas.tseries.offsets.BYearBegin.month\
pandas.tseries.offsets.BYearBegin.n\
pandas.tseries.offsets.BYearBegin.nanos\
pandas.tseries.offsets.BYearBegin.normalize\
pandas.tseries.offsets.BYearBegin.rule_code\
pandas.tseries.offsets.BYearEnd.is_on_offset\
pandas.tseries.offsets.BYearEnd.month\
pandas.tseries.offsets.BYearEnd.n\
pandas.tseries.offsets.BYearEnd.nanos\
pandas.tseries.offsets.BYearEnd.normalize\
pandas.tseries.offsets.BYearEnd.rule_code\
pandas.tseries.offsets.BusinessDay.calendar\
pandas.tseries.offsets.BusinessDay.holidays\
pandas.tseries.offsets.BusinessDay.is_on_offset\
pandas.tseries.offsets.BusinessDay.n\
pandas.tseries.offsets.BusinessDay.nanos\
pandas.tseries.offsets.BusinessDay.normalize\
pandas.tseries.offsets.BusinessDay.rule_code\
pandas.tseries.offsets.BusinessDay.weekmask\
pandas.tseries.offsets.BusinessHour.calendar\
pandas.tseries.offsets.BusinessHour.end\
pandas.tseries.offsets.BusinessHour.holidays\
pandas.tseries.offsets.BusinessHour.is_on_offset\
pandas.tseries.offsets.BusinessHour.n\
pandas.tseries.offsets.BusinessHour.nanos\
pandas.tseries.offsets.BusinessHour.normalize\
pandas.tseries.offsets.BusinessHour.rule_code\
pandas.tseries.offsets.BusinessHour.start\
pandas.tseries.offsets.BusinessHour.weekmask\
pandas.tseries.offsets.BusinessMonthBegin.is_on_offset\
pandas.tseries.offsets.BusinessMonthBegin.n\
pandas.tseries.offsets.BusinessMonthBegin.nanos\
pandas.tseries.offsets.BusinessMonthBegin.normalize\
pandas.tseries.offsets.BusinessMonthBegin.rule_code\
pandas.tseries.offsets.BusinessMonthEnd.is_on_offset\
pandas.tseries.offsets.BusinessMonthEnd.n\
pandas.tseries.offsets.BusinessMonthEnd.nanos\
pandas.tseries.offsets.BusinessMonthEnd.normalize\
pandas.tseries.offsets.BusinessMonthEnd.rule_code\
pandas.tseries.offsets.CustomBusinessDay.calendar\
pandas.tseries.offsets.CustomBusinessDay.holidays\
pandas.tseries.offsets.CustomBusinessDay.is_on_offset\
pandas.tseries.offsets.CustomBusinessDay.n\
pandas.tseries.offsets.CustomBusinessDay.nanos\
pandas.tseries.offsets.CustomBusinessDay.normalize\
pandas.tseries.offsets.CustomBusinessDay.rule_code\
pandas.tseries.offsets.CustomBusinessDay.weekmask\
pandas.tseries.offsets.CustomBusinessHour.calendar\
pandas.tseries.offsets.CustomBusinessHour.end\
pandas.tseries.offsets.CustomBusinessHour.holidays\
pandas.tseries.offsets.CustomBusinessHour.is_on_offset\
pandas.tseries.offsets.CustomBusinessHour.n\
pandas.tseries.offsets.CustomBusinessHour.nanos\
pandas.tseries.offsets.CustomBusinessHour.normalize\
pandas.tseries.offsets.CustomBusinessHour.rule_code\
pandas.tseries.offsets.CustomBusinessHour.start\
pandas.tseries.offsets.CustomBusinessHour.weekmask\
pandas.tseries.offsets.CustomBusinessMonthBegin.calendar\
pandas.tseries.offsets.CustomBusinessMonthBegin.holidays\
pandas.tseries.offsets.CustomBusinessMonthBegin.m_offset\
pandas.tseries.offsets.CustomBusinessMonthBegin.n\
pandas.tseries.offsets.CustomBusinessMonthBegin.nanos\
pandas.tseries.offsets.CustomBusinessMonthBegin.normalize\
pandas.tseries.offsets.CustomBusinessMonthBegin.rule_code\
pandas.tseries.offsets.CustomBusinessMonthBegin.weekmask\
pandas.tseries.offsets.CustomBusinessMonthEnd.calendar\
pandas.tseries.offsets.CustomBusinessMonthEnd.holidays\
pandas.tseries.offsets.CustomBusinessMonthEnd.m_offset\
pandas.tseries.offsets.CustomBusinessMonthEnd.n\
pandas.tseries.offsets.CustomBusinessMonthEnd.nanos\
pandas.tseries.offsets.CustomBusinessMonthEnd.normalize\
pandas.tseries.offsets.CustomBusinessMonthEnd.rule_code\
pandas.tseries.offsets.CustomBusinessMonthEnd.weekmask\
pandas.tseries.offsets.DateOffset.is_on_offset\
pandas.tseries.offsets.DateOffset.n\
pandas.tseries.offsets.DateOffset.nanos\
pandas.tseries.offsets.DateOffset.normalize\
pandas.tseries.offsets.DateOffset.rule_code\
pandas.tseries.offsets.Day.delta\
pandas.tseries.offsets.Day.is_on_offset\
pandas.tseries.offsets.Day.n\
pandas.tseries.offsets.Day.normalize\
pandas.tseries.offsets.Day.rule_code\
pandas.tseries.offsets.Easter.is_on_offset\
pandas.tseries.offsets.Easter.n\
pandas.tseries.offsets.Easter.nanos\
pandas.tseries.offsets.Easter.normalize\
pandas.tseries.offsets.Easter.rule_code\
pandas.tseries.offsets.FY5253.get_rule_code_suffix\
pandas.tseries.offsets.FY5253.get_year_end\
pandas.tseries.offsets.FY5253.is_anchored\
pandas.tseries.offsets.FY5253.is_on_offset\
pandas.tseries.offsets.FY5253.n\
pandas.tseries.offsets.FY5253.nanos\
pandas.tseries.offsets.FY5253.normalize\
pandas.tseries.offsets.FY5253.rule_code\
pandas.tseries.offsets.FY5253.startingMonth\
pandas.tseries.offsets.FY5253.variation\
pandas.tseries.offsets.FY5253.weekday\
pandas.tseries.offsets.FY5253Quarter.get_rule_code_suffix\
pandas.tseries.offsets.FY5253Quarter.get_weeks\
pandas.tseries.offsets.FY5253Quarter.is_anchored\
pandas.tseries.offsets.FY5253Quarter.is_on_offset\
pandas.tseries.offsets.FY5253Quarter.n\
pandas.tseries.offsets.FY5253Quarter.nanos\
pandas.tseries.offsets.FY5253Quarter.normalize\
pandas.tseries.offsets.FY5253Quarter.qtr_with_extra_week\
pandas.tseries.offsets.FY5253Quarter.rule_code\
pandas.tseries.offsets.FY5253Quarter.startingMonth\
pandas.tseries.offsets.FY5253Quarter.variation\
pandas.tseries.offsets.FY5253Quarter.weekday\
pandas.tseries.offsets.FY5253Quarter.year_has_extra_week\
pandas.tseries.offsets.Hour.delta\
pandas.tseries.offsets.Hour.is_on_offset\
pandas.tseries.offsets.Hour.n\
pandas.tseries.offsets.Hour.normalize\
pandas.tseries.offsets.Hour.rule_code\
pandas.tseries.offsets.LastWeekOfMonth.is_on_offset\
pandas.tseries.offsets.LastWeekOfMonth.n\
pandas.tseries.offsets.LastWeekOfMonth.nanos\
pandas.tseries.offsets.LastWeekOfMonth.normalize\
pandas.tseries.offsets.LastWeekOfMonth.rule_code\
pandas.tseries.offsets.LastWeekOfMonth.week\
pandas.tseries.offsets.LastWeekOfMonth.weekday\
pandas.tseries.offsets.Micro.delta\
pandas.tseries.offsets.Micro.is_on_offset\
pandas.tseries.offsets.Micro.n\
pandas.tseries.offsets.Micro.normalize\
pandas.tseries.offsets.Micro.rule_code\
pandas.tseries.offsets.Milli.delta\
pandas.tseries.offsets.Milli.is_on_offset\
pandas.tseries.offsets.Milli.n\
pandas.tseries.offsets.Milli.normalize\
pandas.tseries.offsets.Milli.rule_code\
pandas.tseries.offsets.Minute.delta\
pandas.tseries.offsets.Minute.is_on_offset\
pandas.tseries.offsets.Minute.n\
pandas.tseries.offsets.Minute.normalize\
pandas.tseries.offsets.Minute.rule_code\
pandas.tseries.offsets.MonthBegin.is_on_offset\
pandas.tseries.offsets.MonthBegin.n\
pandas.tseries.offsets.MonthBegin.nanos\
pandas.tseries.offsets.MonthBegin.normalize\
pandas.tseries.offsets.MonthBegin.rule_code\
pandas.tseries.offsets.MonthEnd.is_on_offset\
pandas.tseries.offsets.MonthEnd.n\
pandas.tseries.offsets.MonthEnd.nanos\
pandas.tseries.offsets.MonthEnd.normalize\
pandas.tseries.offsets.MonthEnd.rule_code\
pandas.tseries.offsets.Nano.delta\
pandas.tseries.offsets.Nano.is_on_offset\
pandas.tseries.offsets.Nano.n\
pandas.tseries.offsets.Nano.normalize\
pandas.tseries.offsets.Nano.rule_code\
pandas.tseries.offsets.QuarterBegin.is_anchored\
pandas.tseries.offsets.QuarterBegin.is_on_offset\
pandas.tseries.offsets.QuarterBegin.n\
pandas.tseries.offsets.QuarterBegin.nanos\
pandas.tseries.offsets.QuarterBegin.normalize\
pandas.tseries.offsets.QuarterBegin.rule_code\
pandas.tseries.offsets.QuarterBegin.startingMonth\
pandas.tseries.offsets.QuarterEnd.is_anchored\
pandas.tseries.offsets.QuarterEnd.is_on_offset\
pandas.tseries.offsets.QuarterEnd.n\
pandas.tseries.offsets.QuarterEnd.nanos\
pandas.tseries.offsets.QuarterEnd.normalize\
pandas.tseries.offsets.QuarterEnd.rule_code\
pandas.tseries.offsets.QuarterEnd.startingMonth\
pandas.tseries.offsets.Second.delta\
pandas.tseries.offsets.Second.is_on_offset\
pandas.tseries.offsets.Second.n\
pandas.tseries.offsets.Second.normalize\
pandas.tseries.offsets.Second.rule_code\
pandas.tseries.offsets.SemiMonthBegin.day_of_month\
pandas.tseries.offsets.SemiMonthBegin.is_on_offset\
pandas.tseries.offsets.SemiMonthBegin.n\
pandas.tseries.offsets.SemiMonthBegin.nanos\
pandas.tseries.offsets.SemiMonthBegin.normalize\
pandas.tseries.offsets.SemiMonthBegin.rule_code\
pandas.tseries.offsets.SemiMonthEnd.day_of_month\
pandas.tseries.offsets.SemiMonthEnd.is_on_offset\
pandas.tseries.offsets.SemiMonthEnd.n\
pandas.tseries.offsets.SemiMonthEnd.nanos\
pandas.tseries.offsets.SemiMonthEnd.normalize\
pandas.tseries.offsets.SemiMonthEnd.rule_code\
pandas.tseries.offsets.Tick\
pandas.tseries.offsets.Tick.delta\
pandas.tseries.offsets.Tick.is_on_offset\
pandas.tseries.offsets.Tick.n\
pandas.tseries.offsets.Tick.normalize\
pandas.tseries.offsets.Tick.rule_code\
pandas.tseries.offsets.Week.is_anchored\
pandas.tseries.offsets.Week.is_on_offset\
pandas.tseries.offsets.Week.n\
pandas.tseries.offsets.Week.nanos\
pandas.tseries.offsets.Week.normalize\
pandas.tseries.offsets.Week.rule_code\
pandas.tseries.offsets.Week.weekday\
pandas.tseries.offsets.WeekOfMonth.is_on_offset\
pandas.tseries.offsets.WeekOfMonth.n\
pandas.tseries.offsets.WeekOfMonth.nanos\
pandas.tseries.offsets.WeekOfMonth.normalize\
pandas.tseries.offsets.WeekOfMonth.rule_code\
pandas.tseries.offsets.WeekOfMonth.week\
pandas.tseries.offsets.WeekOfMonth.weekday\
pandas.tseries.offsets.YearBegin.is_on_offset\
pandas.tseries.offsets.YearBegin.month\
pandas.tseries.offsets.YearBegin.n\
pandas.tseries.offsets.YearBegin.nanos\
pandas.tseries.offsets.YearBegin.normalize\
pandas.tseries.offsets.YearBegin.rule_code\
pandas.tseries.offsets.YearEnd.is_on_offset\
pandas.tseries.offsets.YearEnd.month\
pandas.tseries.offsets.YearEnd.n\
pandas.tseries.offsets.YearEnd.nanos\
pandas.tseries.offsets.YearEnd.normalize\
pandas.tseries.offsets.YearEnd.rule_code # There should be no backslash in the final line, please keep this comment in the last ignored function
RET=$(($RET + $?)) ; echo $MSG "DONE"

Currently, some methods fail the GL08 check.

The task here is:

  • take 2-4 methods
  • run: scripts/validate_docstrings.py --format=actions --errors=GL08 method-name
  • check if validation docstrings passes for those methods, and if it’s necessary fix the docstrings according to whatever error is reported
  • remove those methods from code_checks.sh
  • commit, push, open pull request

Please don't comment take as multiple people can work on this issue. You also don't need to ask for permission to work on this, just comment on which methods are you going to work.

If you're new contributor, please check the contributing guide

@jordan-d-murphy
Copy link
Contributor Author

I don't have permission to add them, but this could probably use some labels:

  • CI
  • Docs
  • good first issue

@jordan-d-murphy
Copy link
Contributor Author

addresses #57360

@rhshadrach rhshadrach added Docs CI Continuous Integration good first issue labels Feb 15, 2024
@Mintuagarwal
Copy link

take

@merlinymy
Copy link

working on
pandas.Index.empty\
pandas.Index.names\
pandas.Index.view\

@j36426052
Copy link

working on
pandas.IntervalIndex.left\
pandas.IntervalIndex.length\
pandas.IntervalIndex.mid\

@jordan-d-murphy
Copy link
Contributor Author

Opened a fix for

pandas.DatetimeIndex.as_unit
pandas.DatetimeIndex.freq

@thomasdamcevski
Copy link
Contributor

Working on
pandas.ExcelFile.book
pandas.MultiIndex.codes

@lamdang2k
Copy link
Contributor

Working on
pandas.Timedelta.microseconds
pandas.Timedelta.unit
pandas.Timedelta.value

@jordan-d-murphy
Copy link
Contributor Author

Opened a fix for pandas.core.groupby.SeriesGroupBy.value_counts

@s1099
Copy link
Contributor

s1099 commented Mar 5, 2024

working on

pandas.IntervalIndex.right
pandas.Series.dt

@pmhatre1
Copy link
Contributor

pmhatre1 commented Mar 5, 2024

I am not able to find the proper location.Can anyone help me? I was trying to add docstring for pandas.Period.freq but I am still getting the error " The object does not have a docstring
". I was trying to add docstrig to the 'freq' method for the location pandas/core/arrays/period.py.

@jordan-d-murphy
Copy link
Contributor Author

@pmhatre1 I've had the same experience. I could not locate the correct function to add the docstring to. I've encountered this before, and my suspicion is this is something defined in .pyx and .pyi files and somehow the docstring is invisible to the validations run in code_checks.sh If we could figure out a way to solve this, it would allow us to get fixes for so many of the numpy docstring errors failing validation, sadly, at this time I don't have any solution

@pmhatre1
Copy link
Contributor

Take pandas.Series.dt.freq\
pandas.Series.dt.unit\
pandas.Series.empty\

@pmhatre1
Copy link
Contributor

@pmhatre1 I've had the same experience. I could not locate the correct function to add the docstring to. I've encountered this before, and my suspicion is this is something defined in .pyx and .pyi files and somehow the docstring is invisible to the validations run in code_checks.sh If we could figure out a way to solve this, it would allow us to get fixes for so many of the numpy docstring errors failing validation, sadly, at this time I don't have any solution

I think you are right @jordan-d-murphy. Can we pull in someone here to help us?

@jordan-d-murphy
Copy link
Contributor Author

jordan-d-murphy commented Mar 10, 2024

I would love to hear some ideas from folks that might have suggestions on how to do this. @jrmylow talks about this under [DOC: fix PR02 errors in docstrings](#57111) in this comment here #57111 (comment) maybe we can pursue this?

@jordan-d-murphy
Copy link
Contributor Author

jordan-d-murphy commented Mar 17, 2024

Hi all, if CI: speedup docstring check consecutive runs #57826 gets merged in, I might be reworking our approach here; this would look like closing the following issues:

DOC: fix GL08 errors in docstrings
DOC: fix PR01 errors in docstrings
DOC: fix PR07 errors in docstrings
DOC: fix SA01 errors in docstrings
DOC: fix RT03 errors in docstrings
DOC: fix PR02 errors in docstrings

And opening a new issue to address these based on the new approach.

tl;dr

the work can still be done, but probably under a new ticket once #57826 is merged in

@jordan-d-murphy
Copy link
Contributor Author

@jordan-d-murphy
Copy link
Contributor Author

Opened DOC: Enforce Numpy Docstring Validation (Parent Issue) #58063 as a parent issue for fixing docstrings based on the refactoring in code_checks.sh

Feel free to swing by and help out! 🙂

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CI Continuous Integration Docs good first issue
Projects
None yet
Development

No branches or pull requests

9 participants