Re: [PATCH] Documentation: gpio: add documentation about using software nodes

[Randy Dunlap <rdunlap@infradead.org>]

On 8/11/25 10:17 PM, Dmitry Torokhov wrote:
> Hi Randy,
> 
> On Mon, Aug 11, 2025 at 05:46:02PM -0700, Randy Dunlap wrote:
>> Hi,
>>
>> On 8/11/25 2:30 PM, Dmitry Torokhov wrote:
>>> Introduce documentation regarding use of software nodes to describe
>>> GPIOs on legacy boards that have not been converted to device tree.
>>>
>>
>> Thanks for the additional documentation.
> 
> Thanks for the review.
> 
>>
>>> Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
>>> ---
>>>  Documentation/driver-api/gpio/board.rst       |  64 ++++
>>>  Documentation/driver-api/gpio/index.rst       |   1 +
>>>  .../driver-api/gpio/legacy-boards.rst         | 298 ++++++++++++++++++
>>>  3 files changed, 363 insertions(+)
>>>
>>> diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst
>>> index 4fd1cbd8296e..0cf64e1f2623 100644
>>> --- a/Documentation/driver-api/gpio/board.rst
>>> +++ b/Documentation/driver-api/gpio/board.rst
>>> @@ -94,6 +94,70 @@ with the help of _DSD (Device Specific Data), introduced in ACPI 5.1::
>>>  For more information about the ACPI GPIO bindings see
>>>  Documentation/firmware-guide/acpi/gpio-properties.rst.
>>>  
>>> +Software Nodes
>>> +--------------
>>> +Software nodes allows to construct an in-memory, device-tree-like structure
>>
>>                   allow { drivers | modules | software | us}
>>
>> although "software" seems redundant.
> 
> I changed it to "... allows board specific code ..."
> 
>>
>>> +using ``struct software_node`` and ``struct property_entry``. This structure
>>
>> Quoting Jon (for a different struct):
>>   Better to just say "struct list_head", and the automarkup logic should
>>   take care of the rest.
>>
>> @Jon: ISTM that we need something in Documentation/doc-guide/sphinx.rst (?) about which
>> keywords are handled by automarkup logic. AFAIK, they are struct, union, enum,
>> and typedef (keywords) and function() as indicated by the "()".
> 
> Unfortunately device properties/software nodes are not yet hooked to the
> documentations, so automatic markup/cross referencing does not work.
> 
> I changed this to :c:type:`struct software_node <software_node>`.

Oh no, that's worse from a human readability standpoint. :(

We try (would like to) keep .rst files as readable as .txt files.
All of that extra markup and notation is noisy and usually not needed.
Are you saying that the extra markup (as you listed above) is needed?
for cross-referencing?

The original would be better.

(same in the other .rst file)

-- 
~Randy