Repository navigation
We should remove sectionauthor and moduleauthor directives #180
Description
Activity
Note that the devguide says:
Existing documentation with bylines will not be changed unless the author decides to do so.
The history of authorship is in git
While the history is in Git commit messages, and of course the file content history, it is not in the usual machine-readable “author” field. It needs quite a lot of digging to get at (plus having to know you need to dig).
For your example, the Git history of the file does not mention the original author at all; it ends with a mass addition of ReST documents. These were converted from LaTeX; going further back, you can trace the page to a 1998 commit. Note that whatever the version control system of the time was, it only credited the committer, rather than author, in the metadata.
You can decide the history is not important at this point -- it's not the same ship any more. Or perhaps clarify that the bylines are for old pre-Git credits (maybe rename the directives?).
But just saying “The history of authorship is in git” is misleading.These directives are not rendered in the documentation (afaict)
Indeed, they begin with
..so are RST comments.https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#comments
Note that the devguide says:
Existing documentation with bylines will not be changed unless the author decides to do so.
Note the devguide says in full:
Author attribution
For new documentation, do not use a byline (naming the author of the document). Explicit attribution tends to discourage other users from updating community documentation.
Existing documentation with bylines will not be changed unless the author decides to do so. This is subject to change in the future.
The future is now :)
These directives are not rendered in the documentation (afaict)
Indeed, they begin with .. so are RST comments.
They have double-colons, so they are directives, just like
.. module:: shlexor.. note::.You can decide the history is not important at this point -- it's not the same ship any more. Or perhaps clarify that the bylines are for old pre-Git credits (maybe rename the directives?).
But just saying “The history of authorship is in git” is misleading.You are right, the history is complicated and difficult to fully unearth. These directives don't help much to dig it out, since they are no longer maintained. They don't even capture the full original authorship. Guido is mentioned only five times.
These directives give undue prominence to a small handful of people from one particular point in time.
Author attribution
For new documentation, do not use a byline (naming the author of the document). Explicit attribution tends to discourage other users from updating community documentation.
Existing documentation with bylines will not be changed unless the author decides to do so. This is subject to change in the future.This paragraph is exactly the reason to remove them. We tell people not to use the directives, then tell them that the old directives should stop them from editing pages. We don't believe that anymore, and have not stopped people from editing those pages.
Reacted by Hugo van KemenadeIt is indeed not the same broom. I agree about removing them for the reasons given by that paragraph. They're are only visible in the RST source anyway, and are out of date, as we've had many new authors of both code and docs.
- added a commit that references this issue
on Feb 19, 2026 These directives are not rendered in the documentation (afaict) and they reinforce the incorrect notion that pages are owned by individuals.
What about the
:Author:role? I think it makes this undesired reinforcement as well. And more, it is visible to readers.For whatsnew ones, it could be replace by
:Editors:.What about the
:Author:role? I think it makes this undesired reinforcement as well. And more, it is visible to readers.Yes, those are similar. They are in howto's and whatsnew's; we can deal with those in another pull request.
Reacted by Adorilson Bezerra- added a commit that references this issue
on Feb 19, 2026 - added a commit that references this issue
on Feb 28, 2026 - added a commit that references this issue
on Apr 25, 2026 Yes, those are similar. They are in howto's and whatsnew's; we can deal with those in another pull request.
I wrote python/cpython#151091 to deal with those.
For example: https://github.com/nedbat/cpython/blob/main/Doc/library/shlex.rst
These directives are not rendered in the documentation (afaict) and they reinforce the incorrect notion that pages are owned by individuals. The history of authorship is in git. We should remove them.