Generate table of audit events for docs

[zooba]

BPO	37390
Nosy	@tiran, @ezio-melotti, @merwok, @zooba, @willingc, @JulienPalard, @miss-islington, @tirkarthi
PRs	bpo-37390: Add audit event table to documentations #14406 [3.8] bpo-37390: Add audit event table to documentations (GH-14406) #14429
Files	Screen Shot 2019-06-24 at 11.54.58 pm.png

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-03-30.21:27:52.900>
created_at = <Date 2019-06-24.15:46:04.841>
labels = ['type-feature', '3.8', '3.9', 'docs']
title = 'Generate table of audit events for docs'
updated_at = <Date 2020-03-30.21:27:52.899>
user = 'https://github.com/zooba'

bugs.python.org fields:

activity = <Date 2020-03-30.21:27:52.899>
actor = 'steve.dower'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-03-30.21:27:52.900>
closer = 'steve.dower'
components = ['Documentation']
creation = <Date 2019-06-24.15:46:04.841>
creator = 'steve.dower'
dependencies = []
files = ['48436']
hgrepos = []
issue_num = 37390
keywords = ['patch']
message_count = 14.0
messages = ['346417', '346429', '346436', '346437', '346447', '346652', '346763', '346766', '346804', '347064', '347068', '347092', '347526', '365355']
nosy_count = 9.0
nosy_names = ['christian.heimes', 'ezio.melotti', 'eric.araujo', 'docs@python', 'steve.dower', 'willingc', 'mdk', 'miss-islington', 'xtreak']
pr_nums = ['14406', '14429']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue37390'
versions = ['Python 3.8', 'Python 3.9']

[zooba]

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.

[tirkarthi]

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.

master...tirkarthi:bpo-37390

[zooba]

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

[tirkarthi]

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

[zooba]

I took your code and made some improvements:

master...zooba:bpo-37390

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!

[zooba]

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.

[zooba]

New changeset 44f91c3 by Steve Dower in branch 'master':
bpo-37390: Add audit event table to documentations (GH-14406)
44f91c3

[miss-islington]

New changeset 4fee28a by Miss Islington (bot) in branch '3.8':
bpo-37390: Add audit event table to documentations (GH-14406)
4fee28a

[tirkarthi]

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