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.

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

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 :)

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 :)

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!

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.

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

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

Thanks Steve, the page will serve as a good reference to all audit events.

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.

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

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?

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.

All seems to be fine now.