Currently, we manually write out the Attributes section for every single class. Almost all attributes are simply copied over from the Args section and only a few things change, for the majority of cases:
- The
, optional -> Optional.
- Sequence[...] -> tuple[...]
I propose automating this task. This would help delete thousands of lines of code, make reviewing faster, reduce package size, and also help eliminate a whole class of documentation bugs.
How would this be done? We already do something very similar with the Bot keyword argument insertion and with #5241. This would be done in a similar manner:
- Check if the class has a public attribute not already documented
- If it does, skip, since this was manually documented (perhaps because it's an edge case)
- If it does not, look at the Args section to see if we have the same name so we can copy over the description
- If we do, copy the description, admonitions (like the versionchanged) and apply the transforms as mentioned above
- If we don't, raise a warning, telling the user to manually document since nothing suitable could be found to copy.
There are probably going to be a few edge cases with this logic, which is why the ability to manually document some attributes is a good middle ground.
Currently, we manually write out the Attributes section for every single class. Almost all attributes are simply copied over from the Args section and only a few things change, for the majority of cases:
, optional->Optional.I propose automating this task. This would help delete thousands of lines of code, make reviewing faster, reduce package size, and also help eliminate a whole class of documentation bugs.
How would this be done? We already do something very similar with the Bot keyword argument insertion and with #5241. This would be done in a similar manner:
There are probably going to be a few edge cases with this logic, which is why the ability to manually document some attributes is a good middle ground.