Enhanced the documentation and added examples in pandas tseries offsets Week class #50732

akshay-babbar · 2023-01-13T14:57:15Z

closes DOC: Weekday incompatibility with Python’s demands better documentation #47651 (Replace xxxx with the GitHub issue number)
Tests added and passed if fixing a bug or adding a new feature
All code checks passed.
Added type annotations to new arguments/methods/functions.
Added an entry in the latest doc/source/whatsnew/vX.X.X.rst file if fixing a bug or adding a new feature.

MarcoGorelli

thanks for your pr

got some comments, also there's a merge conflict

MarcoGorelli · 2023-01-13T15:06:00Z

pandas/_libs/tslibs/offsets.pyx

-    Weekly offset.
+        Weekly offset.


please don't change the indendation

MarcoGorelli · 2023-01-13T15:06:31Z

pandas/_libs/tslibs/offsets.pyx

+        ## Below examples explain the usage of this object.
+        ## Importing modules
+        import pandas as pd


I don't think this is necessary, can you try without?

MarcoGorelli · 2023-01-13T15:06:54Z

pandas/_libs/tslibs/offsets.pyx

+        date_format = "%Y-%m-%d"
+        date_object = pd.to_datetime("2023-01-13",format = date_format)
+        print(date_object)
+        ## 2023-01-13 00:00:00


this isn't how we write examples, please check https://pandas.pydata.org/docs/development/contributing_docstring.html

akshay-babbar · 2023-01-13T15:39:49Z

Hey @MarcoGorelli , thanks for the feedback!, I have made the changes you suggested. Please review.

MarcoGorelli

can you check this passes https://pandas.pydata.org/docs/development/contributing_documentation.html#updating-a-pandas-docstring please?

akshay-babbar · 2023-01-13T16:41:24Z

Hey @MarcoGorelli, i passed the validation locally and pushed the changes. Please check.

MarcoGorelli · 2023-01-13T16:46:06Z

pandas/_libs/tslibs/offsets.pyx

+    ---------
+    >>> date_format = "%Y-%m-%d"
+    >>> date_object = pd.to_datetime("2023-01-13",format = date_format)
+    >>> print(date_object)


you don't need print, just something like

>>> date_object '2023-01-13 00:00:00'

(I haven't tried running this, so it may not be exactly correct)

pandas/_libs/tslibs/offsets.pyx

akshay-babbar · 2023-01-13T17:06:55Z

Done the changes, please review.

pandas/_libs/tslibs/offsets.pyx

akshay-babbar · 2023-01-16T10:58:53Z

Hello @MarcoGorelli , is this good to merge or anything else is needed from my end?

MarcoGorelli · 2023-01-16T14:27:54Z

@akshay-babbar a couple of CI jobs are failing, you'll need to fix them up before this can be merged

akshay-babbar · 2023-01-16T14:55:36Z

@MarcoGorelli Atleast one of the two errors is due to the docstring validation which you said can be ignored, for the other pre commit can you please guide me what to do?, cause from my end the code looks just fine.

MarcoGorelli · 2023-01-16T15:56:54Z

you need to address:

 cython-lint.............................................................................................Failed
- hook id: cython-lint
- duration: 5.94s
- exit code: 1

pandas/_libs/tslibs/offsets.pyx:2789:89:  E501 line too long (110 > 88 characters)

and


=================================== FAILURES ===================================
__________________ [doctest] pandas._libs.tslibs.offsets.Week __________________
EXAMPLE LOCATION UNKNOWN, not showing all tests of that example
??? >>> date_object
Expected:
    2023-01-13 00:00:00
Got:
    Timestamp('2023-01-13 00:00:00')

/home/runner/work/pandas/pandas/pandas/_libs/tslibs/offsets.cpython-38-x86_64-linux-gnu.so:None: DocTestFailure
=============================== warnings summary ===============================
../../../micromamba/envs/test/lib/python3.8/site-packages/pytest_cython/plugin.py:57: 40 warnings
  /home/runner/micromamba/envs/test/lib/python3.8/site-packages/pytest_cython/plugin.py:57: PytestRemovedIn8Warning: The (fspath: py.path.local) argument to DoctestModule is deprecated. Please use the (path: pathlib.Path) argument instead.
  See https://docs.pytest.org/en/latest/deprecations.html#fspath-argument-for-node-constructors-replaced-with-pathlib-path
    return DoctestModule.from_parent(parent, fspath=path)

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
------ generated xml file: /home/runner/work/pandas/pandas/test-data.xml -------
============================= slowest 30 durations =============================
0.01s call     pandas/_libs/tslibs/offsets.pyx::pandas._libs.tslibs.offsets.CustomBusinessHour

(29 durations < 0.005s hidden.  Use -vv to show these durations.)
=========================== short test summary info ============================
FAILED pandas/_libs/tslibs/offsets.pyx::pandas._libs.tslibs.offsets.Week
============ 1 failed, 149 passed, 2 skipped, 40 warnings in 0.35s =============

akshay-babbar · 2023-01-16T16:07:15Z

I have made and pushed the changes @MarcoGorelli , thanks for the help. :)

MarcoGorelli · 2023-01-16T17:28:41Z

doesn't look like CI started, could you add another commit (or merge upstream/main) to start it again?

EDIT: I've done this, no need to do anything. this is probably good

MarcoGorelli

this is close 💪

MarcoGorelli · 2023-01-16T20:53:14Z

pandas/_libs/tslibs/offsets.pyx

+    Examples
+    ---------


just noticed, I think the underscores need to be the same length as the title

could you please also build this docstring locally and screenshot it and check it looks alright?

Hi @MarcoGorelli, it looks like this. It looks fine to me :D but should i add one more commit?

that's not the rendered docstring, see https://pandas.pydata.org/docs/dev/development/contributing_documentation.html#building-the-documentation for how to build it

something like

cd doc python make.py clean && python make.py --single pandas.tseries.offsets.Week

Hey @MarcoGorelli , this is the rendered docstring, does this work?

MarcoGorelli · 2023-01-17T12:42:47Z

nice, looks like it renders fine anyway

merging then, thanks @akshay-babbar !

Enhanced the documentation and added examples in ts offsets Week class

f8c5d5d

akshay-babbar mentioned this pull request Jan 13, 2023

DOC: Weekday incompatibility with Python’s demands better documentation #47651

Closed

1 task

MarcoGorelli suggested changes Jan 13, 2023

View reviewed changes

akshay-babbar added 2 commits January 13, 2023 20:59

Fixed indentation and examples in docs

6c8648b

Removed pd import from docs

4f23831

MarcoGorelli suggested changes Jan 13, 2023

View reviewed changes

akshay-babbar added 5 commits January 13, 2023 21:38

Remove extra line breaks in doc strings

b1c6110

Remove extra line breaks in doc strings-v1

de464ec

Remove extra line breaks in doc strings-v2

9a493e9

Added extended summary and see also section

7e3afa3

Added extended summary and see also section-v1

e99a1ec

akshay-babbar force-pushed the offsets-week-doc branch from b373e75 to e99a1ec Compare January 13, 2023 16:36

Merge branch 'main' into offsets-week-doc

9eb2f2e

MarcoGorelli suggested changes Jan 13, 2023

View reviewed changes

Removed extender summary, small cased var names and used pd.Timestamp

f68b9f8

MarcoGorelli suggested changes Jan 13, 2023

View reviewed changes

pandas/_libs/tslibs/offsets.pyx Outdated Show resolved Hide resolved

Added line space

02f7fda

akshay-babbar added 2 commits January 16, 2023 20:57

Merge branch 'main' into offsets-week-doc

0ea315d

Fixed long lines and some print statements

e7282a7

Fixed long lines and some print statements-v1

17d8965

akshay-babbar requested a review from MarcoGorelli January 16, 2023 16:10

Merge branch 'main' into offsets-week-doc

40a2882

MarcoGorelli added this to the 2.0 milestone Jan 16, 2023

MarcoGorelli added the Docs label Jan 16, 2023

MarcoGorelli suggested changes Jan 16, 2023

View reviewed changes

MarcoGorelli approved these changes Jan 17, 2023

View reviewed changes

MarcoGorelli merged commit 4a79485 into pandas-dev:main Jan 17, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enhanced the documentation and added examples in pandas tseries offsets Week class #50732

Enhanced the documentation and added examples in pandas tseries offsets Week class #50732

akshay-babbar commented Jan 13, 2023 •

edited by MarcoGorelli

Loading

MarcoGorelli left a comment

MarcoGorelli Jan 13, 2023

MarcoGorelli Jan 13, 2023

MarcoGorelli Jan 13, 2023

akshay-babbar commented Jan 13, 2023

MarcoGorelli left a comment

akshay-babbar commented Jan 13, 2023

MarcoGorelli Jan 13, 2023

akshay-babbar commented Jan 13, 2023

akshay-babbar commented Jan 16, 2023

MarcoGorelli commented Jan 16, 2023

akshay-babbar commented Jan 16, 2023

MarcoGorelli commented Jan 16, 2023

akshay-babbar commented Jan 16, 2023

MarcoGorelli commented Jan 16, 2023 •

edited

Loading

MarcoGorelli left a comment

MarcoGorelli Jan 16, 2023

akshay-babbar Jan 16, 2023

MarcoGorelli Jan 17, 2023 •

edited

Loading

akshay-babbar Jan 17, 2023

MarcoGorelli commented Jan 17, 2023

Enhanced the documentation and added examples in pandas tseries offsets Week class #50732

Enhanced the documentation and added examples in pandas tseries offsets Week class #50732

Conversation

akshay-babbar commented Jan 13, 2023 • edited by MarcoGorelli Loading

MarcoGorelli left a comment

Choose a reason for hiding this comment

MarcoGorelli Jan 13, 2023

Choose a reason for hiding this comment

MarcoGorelli Jan 13, 2023

Choose a reason for hiding this comment

MarcoGorelli Jan 13, 2023

Choose a reason for hiding this comment

akshay-babbar commented Jan 13, 2023

MarcoGorelli left a comment

Choose a reason for hiding this comment

akshay-babbar commented Jan 13, 2023

MarcoGorelli Jan 13, 2023

Choose a reason for hiding this comment

akshay-babbar commented Jan 13, 2023

akshay-babbar commented Jan 16, 2023

MarcoGorelli commented Jan 16, 2023

akshay-babbar commented Jan 16, 2023

MarcoGorelli commented Jan 16, 2023

akshay-babbar commented Jan 16, 2023

MarcoGorelli commented Jan 16, 2023 • edited Loading

MarcoGorelli left a comment

Choose a reason for hiding this comment

MarcoGorelli Jan 16, 2023

Choose a reason for hiding this comment

akshay-babbar Jan 16, 2023

Choose a reason for hiding this comment

MarcoGorelli Jan 17, 2023 • edited Loading

Choose a reason for hiding this comment

akshay-babbar Jan 17, 2023

Choose a reason for hiding this comment

MarcoGorelli commented Jan 17, 2023

akshay-babbar commented Jan 13, 2023 •

edited by MarcoGorelli

Loading

MarcoGorelli commented Jan 16, 2023 •

edited

Loading

MarcoGorelli Jan 17, 2023 •

edited

Loading