Document signal argument classes

[sebbASF]

• I have searched the issues (including closed ones) and believe that this is not a duplicate.

Issue

There is a list of signals and their arguments here:

pelican/docs/plugins.rst

Line 128 in 1f6b344

List of signals

It would help to provide a link to the actual class names.
For example, what is a metadata argument? Is it a class defined by Pelican? I suspect it is just a dict, but this is not obvious.

Likewise 'pelican object'. This is presumably the class defined here:

pelican/pelican/__init__.py

Line 42 in 1f6b344

class Pelican:

Similarly for all the other argument descriptions.

[justinmayer]

Hi @sebbASF. While I understand how additional clarity about these arguments would be helpful, perma-linking to class names in specific-point-in-time SHA hashes doesn’t seem like a maintainable solution. Folks would follow the links and think they are looking at current code, when in fact years could have passed, and the class behavior could have changed dramatically.

An alternative approach could be to create a new table in the documentation that describes these arguments in more detail, and the argument names in the above-mentioned signals table could link to the argument descriptions in this new table. Someone would have to volunteer to create this new table, however, as we Pelican maintainers are already over-committed. 😅

[sebbASF]

A separate table would be fine.
Once the class names are documented, users can at least search the source for the class name.

Better would be links to documentation such as PyDoc

[justinmayer]

@sebbASF: Is that something you would be willing to help out with?

[sebbASF]

Yes, I should be able to do some of the work

[sebbASF]

Here is my sample table showing the classes for each of the argument names in the signals table.
args.txt

Sorry, but I don't know how to link the entries to each other.