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

bpo-22593: Automate update of Unicode data version in documentation #17748

Open
wants to merge 3 commits into
base: master
from

Conversation

@nmassman
Copy link

nmassman commented Dec 30, 2019

Added a sphinx extension and modified makeunicodedata.py to automate updating documentation with the current Unicode version when it changes.

https://bugs.python.org/issue22593

Copy link
Member

aeros left a comment

Thanks for the PR @nmassman and welcome!

I agree with the general idea behind the PR, it doesn't seem practical to maintain the latest Unicode version in 6 different locations, or for additional ones that are added in the future.

However, a few points (I might think of more later):

  1. You could store the version as a global constant in conf.py, I don't think we need a dedicated text file just to store the latest unicode version.
  2. UNICODE_VERSION or UCS_VERSION would be a far more explicit name for the constant. As far as I'm aware, "UCD" is not a commonly known acronym for Unicode.
  3. IANAL, but I believe there are legal issues associated with copyrighting your own file additions. Our primary means of providing credit/acknowledgement to contributors these days is by adding a Contributed by <name>. sentence at the end of the news entry for the PR. You can add this in yourself.

/cc @merwok

@aeros aeros requested a review from merwok Dec 30, 2019
@ned-deily ned-deily requested a review from JulienPalard Dec 30, 2019
@nmassman

This comment has been minimized.

Copy link
Author

nmassman commented Dec 31, 2019

Thanks for the feedback @aeros

  1. You could store the version as a global constant in conf.py, I don't think we need a dedicated text file just to store the latest unicode version.

I waffled on this a bit, but I went back and took another crack at it. Mostly I wanted to avoid having makeunicodedata.py accidentally mangle conf.py. I think I got it working reliably, though.

  1. UNICODE_VERSION or UCS_VERSION would be a far more explicit name for the constant. As far as I'm aware, "UCD" is not a commonly known acronym for Unicode.

Kinda embarrassed that I didn't clean that up before submitting the PR. I should have slept first. :) I renamed everything to 'UNIDATA_VERSION' to match the original variable in makeunicodedata.py. This could just as easily be changed to 'UNICODE_VERSION', but I erred on the side of staying consistent to what was already in place.

  1. IANAL, but I believe there are legal issues associated with copyrighting your own file additions. Our primary means of providing credit/acknowledgement to contributors these days is by adding a Contributed by <name>. sentence at the end of the news entry for the PR. You can add this in yourself.

I wasn't sure of the convention. I copied the heading format from what was in a few of the other sphinx extensions in the same directory. I inserted the bpo link instead (which was also in one of the other extensions), and updated the news entry.

@merwok

This comment has been minimized.

Copy link
Contributor

merwok commented Dec 31, 2019

I think the comments in the file constitute a change log, not a copyright notice. The copyright situation is already handled by the CLA check, which ensures that the contribution has a suitable license.

It seems OK to me to add a line there, even though there is external history in VCS metadata.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.