classification
Title: Generate table of audit events for docs
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.9, Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: christian.heimes, docs@python, eric.araujo, ezio.melotti, mdk, miss-islington, steve.dower, willingc, xtreak
Priority: normal Keywords: patch

Created on 2019-06-24 15:46 by steve.dower, last changed 2019-07-09 07:36 by steve.dower.

Files
File name Uploaded Description Edit
Screen Shot 2019-06-24 at 11.54.58 pm.png xtreak, 2019-06-24 18:32
Pull Requests
URL Status Linked Edit
PR 14406 merged steve.dower, 2019-06-26 17:57
PR 14429 merged miss-islington, 2019-06-27 17:48
Messages (13)
msg346417 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-06-24 15:46
All audit events are marked in the docs with the ".. audit-event:: <name> <args>" syntax.

We should automatically collate these into a single table and generate a new doc page as part of docs build.
msg346429 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2019-06-24 18:32
I just tried an initial attempt at this and a screenshot as attached. I followed the approach similar to the one at https://www.sphinx-doc.org/en/master/development/tutorials/todo.html to gather all todos. The approach was to append all the audit event directives to a list as they are collected. I then created an AuditEventListDirective for post processing once rst files were read and created an empty page with only the audit-event-list-table directive. I rendered the audit items in the list into a table and then replaced the audit-event-list-table directive in the page with the table content. Unfortunately, I couldn't proceed further due to some odd sphinx error during builds on moving this to a new index and limited sphinx skills. 

+1 to the idea. It would be helpful to have all the audit events under one page for reference.

https://github.com/python/cpython/compare/master...tirkarthi:bpo37390
msg346436 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-06-24 18:52
Awesome! I was just making a start on this too, and it looks like we were doing nearly identical work. Happy to let you keep going on it!

Some things that I thought would be worth doing:
* combine equivalent events (warn if names match but arguments are different)
* include links back to the section where they came from
* include a "CPython implementation detail" message, and maybe mention that the table is generated from the docs

I think for the formatting, we'll have to rearrange how the *args* variable is created initially (so that we store the original names, not the `` marked ones) and then use nodes.literal() when adding them later. But this is pushing the boundaries of my Sphinx/docutils skills as well :)
msg346437 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2019-06-24 19:08
I think my approach suffers from the drawback where duplicate items cannot be separated correctly as you have mentioned. Example as below where socket.connect and socket.connect_ex emit same event and I am not able to retrieve the function at which the audit event block is present thus generating the same entry twice in the table. Maybe I need to store some more metadata.

1153:.. method:: socket.connect(address)
1165:   .. audit-event:: socket.connect "self address"
1174:.. method:: socket.connect_ex(address)
1183:   .. audit-event:: socket.connect "self address"

> * include links back to the section where they came from

Sphinx doesn't seem to support hyperlinking to line numbers. One approach would be to just link to the functions that emit the events that could solve the above problem too.

I did this as a PoC and kind of stuck with moving the file to a separate to a different table of content. I also seemed to have hit a sphinx bug that I couldn't get out of and my skills are limited too in Sphinx. I will give it another try over this week to see if I can come up with something mergeable :)
msg346447 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-06-24 23:01
I took your code and made some improvements:

https://github.com/python/cpython/compare/master...zooba:bpo37390

In particular, I added the backlinks from the table (but unfortunately they all go to the line of text we generate for the ..audit-event directive, and not the top of the section :( ) and debugged some of the weirdness of generating tables in docutils.

Feel free to pull my changes and take back over if there's more you want to do!
msg346652 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-06-26 17:59
I think my PR is ready. I had to go through and update all the audit-event tags that existed, since the argument parsing in Sphinx didn't work the way I first thought it did, but now we can provide a back reference manually (or let it auto-generate one to the line with the event).

I also updated some of the event names I recently added so they are more consistent with the existing ones - e.g. poplib.POP3 -> poplib.connect for consistency with socket.connect.
msg346763 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-06-27 17:48
New changeset 44f91c388a6f4da9ed3300df32ca290b8aa104ea by Steve Dower in branch 'master':
bpo-37390: Add audit event table to documentations (GH-14406)
https://github.com/python/cpython/commit/44f91c388a6f4da9ed3300df32ca290b8aa104ea
msg346766 - (view) Author: miss-islington (miss-islington) Date: 2019-06-27 18:07
New changeset 4fee28aa42dbac7f08a6d2829546b7d8e848034d by Miss Islington (bot) in branch '3.8':
bpo-37390: Add audit event table to documentations (GH-14406)
https://github.com/python/cpython/commit/4fee28aa42dbac7f08a6d2829546b7d8e848034d
msg346804 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2019-06-28 06:40
Thanks Steve, the page will serve as a good reference to all audit events.
msg347064 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-07-01 19:04
The page is not generating correctly at https://docs.python.org/dev/library/audit_events.html

Adding the documentation team, where hopefully someone will know what needs poking.
msg347068 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2019-07-01 19:42
Strange, I bet that I have seen this rendered table while the issue was closed. The docs table renders fine locally on latest master. Given that Audit event, Arguments and References table header are rendered with the table being replaced I guess somehow env.all_audit_events is empty. Is there something related to storing it with env? I hope docs CI to generate html daily is also done in a clean state like locally. Is it possible to get archives of docs releases to see from when this was missing as in https://docs.python.org/3.9/download.html
msg347092 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-07-01 23:41
I can't repro this. It looks like Doc/makefile#L196 passes -Ea which ought to deal with any old files (and it certainly does on my Ubuntu machine), so it's likely not that.

The table contents is simply not in the file on docs.p.o, so I guess there's something in the build process that's failing? Or the environment is not making it to the output stage for some reason?
msg347526 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-07-09 07:36
Anyone from the docs team have any ideas here? We're going to present on this at EuroPython tomorrow and it'd be great to be able to point people at the docs.
History
Date User Action Args
2019-07-09 07:36:40steve.dowersetmessages: + msg347526
2019-07-01 23:41:57steve.dowersetmessages: + msg347092
2019-07-01 19:42:46xtreaksetmessages: + msg347068
2019-07-01 19:04:34steve.dowersetstatus: closed -> open

nosy: + ezio.melotti, eric.araujo, willingc, mdk
messages: + msg347064

resolution: fixed ->
stage: resolved -> needs patch
2019-06-28 06:40:50xtreaksetmessages: + msg346804
2019-06-27 18:10:20steve.dowersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-06-27 18:07:20miss-islingtonsetnosy: + miss-islington
messages: + msg346766
2019-06-27 17:48:15miss-islingtonsetpull_requests: + pull_request14245
2019-06-27 17:48:04steve.dowersetmessages: + msg346763
2019-06-26 17:59:30steve.dowersetmessages: + msg346652
2019-06-26 17:57:05steve.dowersetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request14218
2019-06-24 23:01:38steve.dowersetmessages: + msg346447
2019-06-24 19:08:04xtreaksetmessages: + msg346437
2019-06-24 18:52:52steve.dowersetmessages: + msg346436
2019-06-24 18:32:23xtreaksetfiles: + Screen Shot 2019-06-24 at 11.54.58 pm.png

messages: + msg346429
2019-06-24 16:11:29xtreaksetnosy: + xtreak
2019-06-24 15:46:04steve.dowercreate