-
-
Notifications
You must be signed in to change notification settings - Fork 18.2k
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: Change release and whatsnew #21599
DOC: Change release and whatsnew #21599
Conversation
Changes: * We will include the correct (latest on master or maintenance branch) whatsnew directly in the index.rst toctree * Contributors are included in the whatsnew for each version (automatically) * Removed release.rst * Added new releases.rst which has toctrees for each release Incidental changes * Updated style.ipynb. Writing the jinja template was confusing sphinx. We included it in the git source now. * Fixing some inconsitent header levels (will do more) * Refactored announce.py to support auto-generated contributors
doc/source/conf.py
Outdated
source_suffix = '.rst' | ||
source_suffix = [ | ||
'.rst', | ||
'.txt', |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
required so that the whatsnew files can be included in the toctree.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there actually a reason they are not *.rst ?
@@ -298,8 +303,39 @@ | |||
for page in moved_api_pages | |||
} | |||
|
|||
|
|||
common_imports = """\ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Previously we had this at the top of whatsnew.rst. Now it has to be in every whatsnew/v0.x.x.txt
, as they are no longer literally included below this. Usage is just {{ common_imports }}
doc/source/conf.py
Outdated
'v0.23.2': announce.build_string('v0.23.1..HEAD'), | ||
'v0.23.1': announce.build_string('v0.23.0..v0.23.1'), | ||
'v0.23.0': announce.build_string('v0.22.0..v0.23.0'), | ||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is run every time we build the docs. It'll probably be run even for single page / docstring ones. I was concerned it would take a while, but it's surprisingly fast.
Once I finish the rest of the whatsnew, I'll time it again and look into ways of speeding it up if is a problem.
""" | ||
# http://ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/ | ||
# Make sure we're outputting HTML | ||
if app.builder.format != 'html': |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm I should look into what happens for PDF. We should be able to handle it just fine.
@@ -118,7 +118,7 @@ See the package overview for more detail about what's in the library. | |||
{{ single_doc }} | |||
{% endif -%} | |||
{% if not single_doc -%} | |||
whatsnew | |||
What's New <whatsnew/v0.24.0> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We'll update this as part of the post-release process.
Codecov Report
@@ Coverage Diff @@
## master #21599 +/- ##
=======================================
Coverage 92.24% 92.24%
=======================================
Files 161 161
Lines 51340 51340
=======================================
Hits 47361 47361
Misses 3979 3979
Continue to review full report at Codecov.
|
Looks really good. There is just one thing that I'd consider changing. I don't think it's a good practice to import functions from What I'd do instead is creating somewhere a directory "dev utils", where we can not only have the code of |
Hello @TomAugspurger! Thanks for updating the PR. Cheers ! There are no PEP8 issues in this Pull Request. 🍻 Comment last updated on June 26, 2018 at 12:00 Hours UTC |
doc/source/conf.py
Outdated
tags = [x.name for x in repo.tags if xpr.match(str(x))] | ||
versions = sorted(zip(tags, | ||
[tuple(map(int, xpr.match(x).groups())) for x in tags]), | ||
key=lambda x: x[1]) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In case you don't know it, distutils
provides a class to parse, sort... versions. You'd need to get rid of the heading v
in v0.23.1
. But then you can do this stuff automatically. For example:
>>> import distutils.version
>>> tags = ['0.22.0', '0.23.0', '0.23.1', '0.21.1', '0.21.0']
>>> versions = map(distutils.version.StrictVersion, tags)
>>> versions = sorted(versions)
>>> versions[-1].version
(0, 23, 1)
Sorry I didn't mean to push those changes. Not sure whether it's worth auto-discovering. |
Cool! Didn't have time to look into detail yet (will do that tomorrow), but some very quick feedback:
|
+ 1. We can maybe also put things in or alongside doc/make.py ? |
Sure.
Which ones? Anything using the "canonical" format like
Agreed. I think
I would slightly prefer to generate it dynamically. My goal is to remove the "final doc update" commit that's currently part of the release process. In theory, it should be possible to make this a Jinja2 macro that is called inside the actual whatsnew, rather than ahead of time. |
I think it used to be to avoid warnings that they weren't included in a
toctree? Maybe we can just change them.
…On Mon, Jun 25, 2018 at 3:51 PM, Joris Van den Bossche < ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In doc/source/conf.py
<#21599 (comment)>:
> @@ -120,7 +122,10 @@
templates_path = ['../_templates']
# The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = [
+ '.rst',
+ '.txt',
Is there actually a reason they are not *.rst ?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#21599 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/ABQHIpGSK_j6L7FGlRHyK7AuMuGtSKBZks5uAU1pgaJpZM4U0XNK>
.
|
Because it are now all separate pages, the url changes. For example, the first link in the highlights section of 0.23.0 points to http://pandas.pydata.org/pandas-docs/stable/whatsnew.html#whatsnew-0230-enhancements-round-trippable-json. However, with this change the link will end in .../whatsnew/v0.23.0.html#whatsnew-0230-enhancements-round-trippable-json |
scripts/announce.py
Outdated
print(heading) | ||
print(u"=" * len(heading)) | ||
print(author_msg % len(authors)) | ||
uline = '=' * len(heading) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this header does not always match the header levels in the whatsnew file
doc/source/conf.py
Outdated
'v0.21.0': announce.build_string('v0.10.0..v0.21.0'), | ||
'v0.21.1': announce.build_string('v0.10.0..v0.21.1'), | ||
'v0.22.0': announce.build_string('v0.10.0..v0.22.0'), | ||
'v0.22.0': announce.build_string('v0.22.0..v0.23.0'), |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I suppose you know you still have some typos here (a lot of "v0.10.0" above, and this line is duplicated)
Yeah, I'm removing all this. Didn't mean to push it.
I tried to write a new sphinx directive, so we can just do `..
contributors:: v0.23.1..v0.23.2`, but didn't get the rendering of the
inserted text to work yet.
…On Tue, Jun 26, 2018 at 3:31 AM, Joris Van den Bossche < ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In scripts/announce.py
<#21599 (comment)>:
> authors = get_authors(revision_range)
- heading = u"Contributors"
- print()
- print(heading)
- print(u"=" * len(heading))
- print(author_msg % len(authors))
+ uline = '=' * len(heading)
this header does not always match the header levels in the whatsnew file
------------------------------
In doc/source/conf.py
<#21599 (comment)>:
> + 'v0.16.2': announce.build_string('v0.16.1..v0.16.2'),
+ 'v0.17.0': announce.build_string('v0.16.2..v0.17.0'),
+ 'v0.17.1': announce.build_string('v0.17.0..v0.17.1'),
+ 'v0.18.0': announce.build_string('v0.10.0..v0.18.0'),
+ 'v0.18.1': announce.build_string('v0.10.0..v0.18.1'),
+ 'v0.19.0': announce.build_string('v0.10.0..v0.19.0'),
+ 'v0.19.1': announce.build_string('v0.10.0..v0.19.1'),
+ 'v0.19.2': announce.build_string('v0.10.0..v0.19.2'),
+ 'v0.20.0': announce.build_string('v0.10.0..v0.20.0'),
+ 'v0.20.1': announce.build_string('v0.10.0..v0.20.1'),
+ 'v0.20.2': announce.build_string('v0.10.0..v0.20.2'),
+ 'v0.20.3': announce.build_string('v0.10.0..v0.20.3'),
+ 'v0.21.0': announce.build_string('v0.10.0..v0.21.0'),
+ 'v0.21.1': announce.build_string('v0.10.0..v0.21.1'),
+ 'v0.22.0': announce.build_string('v0.10.0..v0.22.0'),
+ 'v0.22.0': announce.build_string('v0.22.0..v0.23.0'),
I suppose you know you still have some typos here (a lot of "v0.10.0"
above, and this line is duplicated)
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#21599 (review)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/ABQHIkE93cGThlHgr7y1seHnce7EFJKDks5uAfFPgaJpZM4U0XNK>
.
|
Ok, cleaned up my mess from yesterday. Replaced with a custom directive so we write
rather than building them up ahead of time. I haven't updated all the old files yet. |
Will think about the links as well. Writing the directive took a long time (I didn't realize I had to build the list of elements myself. I was hoping I could just pass it a string and have sphinx parse it), so I'm not sure I'll have time to finish this for 0.23.2. |
no problem, we can still go the normal way for that |
Updated the headers. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks like you inadvertently edited the wrong file
doc/source/whatsnew/v0.20.2.rst
Outdated
v0.20.2 (June 4, 2017) | ||
---------------------- | ||
What's new in v0.20.2 (June 4, 2017) | ||
------------------------------------ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Are you sure you wanted to do this in v.0.20.2
(which further increases the inconsistency) rather than v.0.24.0
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Alternatively, you could add "What's new in " to all versions (which would be even better than introducing it starting with 0.23.0)
I think I needed to change the 0.23+ headers to get the levels consistent. Not super interested in changing the old ones. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some tiny style comments, but nothing blocking. Also, you seem to have closed the PR by accident.
I think I needed to change the 0.23+ headers to get the levels consistent. Not super interested in changing the old ones.
Fair enough.
@@ -1,7 +1,9 @@ | |||
.. _whatsnew_0230: | |||
|
|||
v0.23.0 (May 15, 2018) | |||
---------------------- | |||
What's new in 0.23.0 (May 15, 2018) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not a big deal, but "new" is capitalized for all the others. I'd go with lower-case for all.
upgrade instructions, see :ref:`install`. | ||
|
||
0.24 release | ||
------------ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it would look better (also looking at your render from the OP) to have
+ Version 0.24
- 0.24 release
------------
etc.
All green. Merging before we have more conflicts :) I think this will require all outstanding PRs adding a release note to merge master. But contributors shouldn't have to manually fix any conflicts; git will handle things automatically. |
* upstream/master: (25 commits) DOC: Delete trailing blank lines in docstrings. (pandas-dev#23651) DOC: Change release and whatsnew (pandas-dev#21599) DOC: Fix format of the See Also descriptions (pandas-dev#23654) DOC: update pandas.core.groupby.DataFrameGroupBy.resample docstring. (pandas-dev#20374) ENH: Allow export of mixed columns to Stata strl (pandas-dev#23692) CLN: Remove unnecessary code (pandas-dev#23696) Pin flake8-rst version (pandas-dev#23699) Implement _most_ of the EA interface for DTA/TDA (pandas-dev#23643) CI: raise clone depth limit on CI BUG: Fix Series/DataFrame.rank(pct=True) with more than 2**24 rows (pandas-dev#23688) REF: Move Excel names parameter handling to CSV (pandas-dev#23690) DOC: Accessing files from a S3 bucket. (pandas-dev#23639) Fix errorbar visualization (pandas-dev#23674) DOC: Surface / doc mangle_dupe_cols in read_excel (pandas-dev#23678) DOC: Update is_sparse docstring (pandas-dev#19983) BUG: Fix read_excel w/parse_cols & empty dataset (pandas-dev#23661) Add to_flat_index method to MultiIndex (pandas-dev#22866) CLN: Move to_excel to generic.py (pandas-dev#23656) TST: IntervalTree.get_loc_interval should return platform int (pandas-dev#23660) CI: Allow to compile docs with ipython 7.11 pandas-dev#22990 (pandas-dev#23655) ...
…fixed * upstream/master: DOC: Delete trailing blank lines in docstrings. (pandas-dev#23651) DOC: Change release and whatsnew (pandas-dev#21599) DOC: Fix format of the See Also descriptions (pandas-dev#23654) DOC: update pandas.core.groupby.DataFrameGroupBy.resample docstring. (pandas-dev#20374) ENH: Allow export of mixed columns to Stata strl (pandas-dev#23692) CLN: Remove unnecessary code (pandas-dev#23696) Pin flake8-rst version (pandas-dev#23699) Implement _most_ of the EA interface for DTA/TDA (pandas-dev#23643) CI: raise clone depth limit on CI BUG: Fix Series/DataFrame.rank(pct=True) with more than 2**24 rows (pandas-dev#23688) REF: Move Excel names parameter handling to CSV (pandas-dev#23690) DOC: Accessing files from a S3 bucket. (pandas-dev#23639) Fix errorbar visualization (pandas-dev#23674) DOC: Surface / doc mangle_dupe_cols in read_excel (pandas-dev#23678) DOC: Update is_sparse docstring (pandas-dev#19983) BUG: Fix read_excel w/parse_cols & empty dataset (pandas-dev#23661) Add to_flat_index method to MultiIndex (pandas-dev#22866) CLN: Move to_excel to generic.py (pandas-dev#23656) TST: IntervalTree.get_loc_interval should return platform int (pandas-dev#23660)
@TomAugspurger the doc build is failing
maybe because it has not a full clone? |
Fixed (avoided) in #23714.
I think you're right about the clone depth. Not a huge deal for the CI,
though I'm a bit concerned things
will be broken when we get to release time, and we'll need to scramble last
minute to fix it.
…On Thu, Nov 15, 2018 at 4:26 AM Joris Van den Bossche < ***@***.***> wrote:
@TomAugspurger <https://github.com/TomAugspurger> the doc build is failing
Exception occurred:
File "/home/travis/miniconda3/envs/pandas/lib/python3.6/site-packages/git/cmd.py", line 825, in execute
raise GitCommandError(command, status, stderr_value, stdout_value)
git.exc.GitCommandError: Cmd('git') failed due to: exit code(128)
cmdline: git shortlog -s v0.9.0..v0.10.0
stderr: 'fatal: ambiguous argument 'v0.9.0..v0.10.0': unknown revision or path not in the working tree.
maybe because it has not a full clone?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#21599 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/ABQHIk_mCAgrqJKe4SdFzBTNPzFCilaqks5uvUFLgaJpZM4U0XNK>
.
|
@TomAugspurger Thanks! It would still be nice to have it run at the CI as well, as I would imagine that at some point we would like to rely on some CI service to build the docs and upload that version, instead of having the release manager it to do locally? |
Yeah, I'm not sure what's best here...
For now, we could hard code a `git fetch origin
refs/tags/v0.23.4:refs/tags/v0.23.4` before doing the doc build.
But then that's one more thing to remember to update manually, which was
the entire point of this PR :)
…On Thu, Nov 15, 2018 at 6:56 AM Joris Van den Bossche < ***@***.***> wrote:
@TomAugspurger <https://github.com/TomAugspurger> Thanks!
It would still be nice to have it run at the CI as well, as I would
imagine that at some point we would like to rely on some CI service to
build the docs and upload that version, instead of having the release
manager it to do locally?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#21599 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/ABQHIty2L_XafvEKYdEqwamcpEuDmhJRks5uvWSRgaJpZM4U0XNK>
.
|
* DOC: Change release and whatsnew Changes: * We will include the correct (latest on master or maintenance branch) whatsnew directly in the index.rst toctree * Contributors are included in the whatsnew for each version (automatically) * Removed release.rst * Added new releases.rst which has toctrees for each release Incidental changes * Updated style.ipynb. Writing the jinja template was confusing sphinx. We included it in the git source now. * Fixing some inconsitent header levels (will do more) * Refactored announce.py to support auto-generated contributors
* DOC: Change release and whatsnew Changes: * We will include the correct (latest on master or maintenance branch) whatsnew directly in the index.rst toctree * Contributors are included in the whatsnew for each version (automatically) * Removed release.rst * Added new releases.rst which has toctrees for each release Incidental changes * Updated style.ipynb. Writing the jinja template was confusing sphinx. We included it in the git source now. * Fixing some inconsitent header levels (will do more) * Refactored announce.py to support auto-generated contributors
* DOC: Change release and whatsnew Changes: * We will include the correct (latest on master or maintenance branch) whatsnew directly in the index.rst toctree * Contributors are included in the whatsnew for each version (automatically) * Removed release.rst * Added new releases.rst which has toctrees for each release Incidental changes * Updated style.ipynb. Writing the jinja template was confusing sphinx. We included it in the git source now. * Fixing some inconsitent header levels (will do more) * Refactored announce.py to support auto-generated contributors
Some cleanup & changes to facilitate release automation
whatsnew directly in the index.rst toctree
Incidental changes
included it in the git source now.
TODO:
cc @jorisvandenbossche, @datapythonista