peps
peps copied to clipboard
python
Infra: Add pep2bib.py for generating BibTeX entries
This PR adds a pep2bib.py script, which generates a bibtex file for use in LaTeX.
An example entry looks like this:
@techreport{pep634,
author = "Brandt Bucher and Guido van Rossum",
title = "PEP 634: Structural Pattern Matching: Specification",
institution = "Python Software Foundation",
year = "2020",
month = sep,
type = "PEP",
number = "634",
url = "https://www.python.org/dev/peps/pep-0634/"
}
Should you think that this repository is not the right place to host this script just close the PR and I'll try to maintain it in a separate repository. Having it in here would make it more discoverable for other people needing to cite PEPs though.
I'd generally be in favour of this, with two caveats.
- is is possible to avoid the extra dependency?
- we should really tighten the pep parsing helpers -- currently they use pure Docutils, so don't take advantage of e.g. the role overrides defined in
pep2html. In addition, if PEP 676 is approved I imagine Sphinx-exclusive syntax will start to be used, which the parsing helpers would entirely error on. Not asking you to solve the problem in this PR, more something we need to consider (although perhaps only after PEP 676 has been pronounced upon)
Generating the bib file manually instead of using a library shouldn't be too hard. I'd have to look into how exactly escaping in bib works. Other than that it should be pretty straight forward. That would eliminate the additional dependency.
I agree it makes sense to integrate into the website (either in a peps.python.org/tools or on each page).
I don't want to ask you to do work that may prove fruitless, so @freundTech it may be best to hold off for a short while to see if PEP 676 gets accepted. I can then give you pointers on where we'd want to integrate this.
Cam points out we require Python 3.9 as a minimum, which might also allow for slightly cleaner code when it comes to it.
A
Cam points out we require Python 3.9 as a minimum, which might also allow for slightly cleaner code when it comes to it.
Yeah, there is a lot of cruft that could be cleaned up here, but I didn't comment on anything that followed the pattern of the other similarly-named legacy scripts here (the creation of which as a formal PEP post-dated pep2html.py by a year, and for which Python 1.5 was the latest released version at the time), which I assumed the author's intent was to match.
Sidenote: Technically, our build job (for the legacy build system) is still hard-pinned to Python 3.8 (which I was going to fix in a forthcoming PR), which is why I mentioned 3.8/3.9 instead of just 3.9.
which I was going to fix in a forthcoming PR
Personally I'd hold off on updating it -- it requires at least testing to ensure everything works, and (contingent on 676 being accepted) the file will just be deleted.
I won't object if you want to do the work, though!
Personally I'd hold off on updating it -- it requires at least testing to ensure everything works, and (contingent on 676 being accepted) the file will just be deleted.
Good point; I was going to update a few other things (the linting, etc) and was prepared to fully test it but wasn't sure of the timeline on that. To note, is there a reason we don't have at least the non-deploy steps of deploy-gh-pages.yml running in a workflow triggered on PRs (as well as main, where it is already running), to ensure the new build system works in parallel to the old during this consideration/transition period, to ensure there isn't a regression or other change (in the build system or the reST source files) that breaks it but not the legacy one? For now I've just been manually testing all my PRs on both every time I make a change, which gets a bit tedious.
To note, is there a reason we don't have at least the non-deploy steps of deploy-gh-pages.yml running in a workflow triggered on PRs (as well as main, where it is already running), to ensure the new build system works in parallel to the old during this consideration/transition period, to ensure there isn't a regression or other change (in the build system or the reST source files) that breaks it but not the legacy one? For now I've just been manually testing all my PRs on both every time I make a change, which gets a bit tedious.
fixed
Is making PEPs easier to cite a good change? I worry about people who miss the fact that most PEPs are initial design discussions rather than documentation.
@encukou -- I'd agree, but guys that are going to cite PEPs will cite PEPs regardless, so a page with the button that also has a paragraph noting what you said may sway the more conscientious cite-or.
A PEP also has the benefit that it changes much less than documentation, making it marginally easier to cite, correctness aside.
If we add this feature here, perhaps a similar one might be considered for the Python docs in general?
A
Not to mention, the more likely alternative is that people don't cite anything, so better to cite the PEP than nothing...and generally, academic citations (likely most people using BibTeX, including myself) are much more likely to be interested in design discussion, motivation and rationale, and perhaps (in many PEPs) a formal specification, rather than implementation documentation—and in academia, one often needs to cite the foundational papers that incipiated a specific idea, alongside more current work on the topic, tracing the thread of knowledge back whence it came.
I don't want to ask you to do work that may prove fruitless, so @freundTech it may be best to hold off for a short while to see if PEP 676 gets accepted. I can then give you pointers on where we'd want to integrate this.
PEP 676 has been accepted.
My current thoughts are adding a step to the build process to generate a .bib file for each PEP (using this script or similar), and add a download link for each one in the PEP sidebar.
A