Inconsistent format to list attributes in Data Model section

[adorilson]

Documentation

Object attributes are listed several times in the Data Model section. However, there is no standard format.
It was used:

1. table, for example, in User defined functions
2. list, for example, in Modules
3. in line, for example, in Code Objects

It must be standardized. But what will be the choice? In line is the worst. It is not a choice.
But about table or list?

Linked PRs

• gh-111746: Doc: Format built-in function's attributes #113574

[hugovk]

Screenshots:

1. table, for example, in User defined functions

Table

2. list, for example, in Modules

List

3. in line, for example, in Code Objects

In line

It must be standardized. But what will be the choice? In line is the worst. It is not a choice. But about table or list?

Standardising can help, although I wouldn't say it must be done, but we should pick the best tool to present the information in each case. I agree the inline ones need changing (Google calls these "embedded" or "run-in" lists and recommends transforming into bulleted or numbered lists: https://developers.google.com/tech-writing/one/lists-and-tables).

For accessibility, this 2012 article recommends tables over definition lists (which is what example 2 is):
https://snook.ca/archives/html_and_css/definition-lists-v-tables

However, this 2022 post says support for definition lists is generally good, and this 2017 says tables are OK too:

• https://adrianroselli.com/2022/12/brief-note-on-description-list-support.html
• https://adrianroselli.com/2017/11/hey-its-still-ok-to-use-tables.html

---

So let's compare what info is being conveyed in these three examples.

The table of "special attributes" has three columns:

• name
• meaning
• writable/read-only

The definition list has "predefined (writable) attributes":

• name
• meaning

Followed by a single "special read-only attribute":

• name
• meaning

These could be combined into a single table, but I'm not entirely clear on the difference between "predefined (writable)" and "special read-only".

Finally, the inline descriptions are all "special read-only attributes":

• name
• meaning

I guess a definition list would suffice for those with just two headers, although tables are a more compact, and it's a problem that this page is already so long.

What do you think?

If we go for tables, I suggest using list-table markup, it makes things easier to edit in the future than adjusting whitespace in grid tables:

• https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/#tables

[adorilson]

Thanks for the deep analysis, @hugovk .

In this case, I think a table is more suitable.
Concerning "predefined", "special only" and other field details, I think a "Notes" column can be used for this,
as already done in some cases.

[hugovk]

Would you like to put together a PR? Feel free to do them one at a time, if it's easier.

[adorilson]

At some moment in the future, I can do that. However, if somebody more available wants to do this, go ahead.