Atomic types, atomic bitops, and memory barriers docs are included in kernel
docs build since commit e40573a43d163a ("docs: put atomic*.txt and
memory-barriers.txt into the core-api book") as a wrapper stub for
corresponding uncoverted txt docs. Let's turn them into full-fledged reST docs. 

Bagas Sanjaya (4):
  Documentation: memory-barriers: Convert to reST format
  Documentation: atomic_bitops: Convert to reST format
  Documentation: atomic_t: Convert to reST format
  Documentation: atomic_bitops, atomic_t, memory-barriers: Link to
    newly-converted docs

 Documentation/RCU/rcu_dereference.rst         |    2 +-
 .../atomic_bitops.rst}                        |   43 +-
 .../{atomic_t.txt => core-api/atomic_t.rst}   |  211 ++-
 Documentation/core-api/circular-buffers.rst   |    4 +-
 Documentation/core-api/index.rst              |    6 +-
 .../memory-barriers.rst}                      | 1594 +++++++++--------
 Documentation/core-api/refcount-vs-atomic.rst |    5 +-
 .../core-api/wrappers/atomic_bitops.rst       |   18 -
 Documentation/core-api/wrappers/atomic_t.rst  |   19 -
 .../core-api/wrappers/memory-barriers.rst     |   18 -
 Documentation/driver-api/device-io.rst        |    4 +-
 Documentation/locking/spinlocks.rst           |    5 +-
 Documentation/virt/kvm/vcpu-requests.rst      |    4 +-
 13 files changed, 1000 insertions(+), 933 deletions(-)
 rename Documentation/{atomic_bitops.txt => core-api/atomic_bitops.rst} (54%)
 rename Documentation/{atomic_t.txt => core-api/atomic_t.rst} (67%)
 rename Documentation/{memory-barriers.txt => core-api/memory-barriers.rst} (67%)
 delete mode 100644 Documentation/core-api/wrappers/atomic_bitops.rst
 delete mode 100644 Documentation/core-api/wrappers/atomic_t.rst
 delete mode 100644 Documentation/core-api/wrappers/memory-barriers.rst


base-commit: cae58415830f326822593ec01deebe5fdaeb33a2
-- 
An old man doll... just what I always wanted! - Clara

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> Atomic types, atomic bitops, and memory barriers docs are included in kernel
> docs build since commit e40573a43d163a ("docs: put atomic*.txt and
> memory-barriers.txt into the core-api book") as a wrapper stub for
> corresponding uncoverted txt docs. Let's turn them into full-fledged reST docs. 

Did it occur to you to look at the changelog for the commit you cite,
which explains why those documents are handled the way they are...?

jon

Jonathan Corbet <corbet@lwn.net> writes:

> Bagas Sanjaya <bagasdotme@gmail.com> writes:
>
>> Atomic types, atomic bitops, and memory barriers docs are included in kernel
>> docs build since commit e40573a43d163a ("docs: put atomic*.txt and
>> memory-barriers.txt into the core-api book") as a wrapper stub for
>> corresponding uncoverted txt docs. Let's turn them into full-fledged reST docs. 
>
> Did it occur to you to look at the changelog for the commit you cite,
> which explains why those documents are handled the way they are...?

I'm sorry, that caught me at the wrong time, and I was rather more harsh
than I should have been.  I should not have responded that way.

For future reference, though, when somebody has gone out of their way to
accomplish a task in a specific way, there usually *is* a reason for it.
If you can't find that reason, the best thing to do is usually to ask.

Thanks,

jon

On Thu, Jul 17, 2025 at 03:06:13PM +0700, Bagas Sanjaya wrote:
> Atomic types, atomic bitops, and memory barriers docs are included in kernel
> docs build since commit e40573a43d163a ("docs: put atomic*.txt and
> memory-barriers.txt into the core-api book") as a wrapper stub for
> corresponding uncoverted txt docs. Let's turn them into full-fledged reST docs. 
> 
> Bagas Sanjaya (4):
>   Documentation: memory-barriers: Convert to reST format
>   Documentation: atomic_bitops: Convert to reST format
>   Documentation: atomic_t: Convert to reST format
>   Documentation: atomic_bitops, atomic_t, memory-barriers: Link to
>     newly-converted docs

NAK

If these are merged I will no longer touch / update these files.

On Thu, 17 Jul 2025 12:55:54 +0200
Peter Zijlstra <peterz@infradead.org> wrote:

> On Thu, Jul 17, 2025 at 03:06:13PM +0700, Bagas Sanjaya wrote:
> > Atomic types, atomic bitops, and memory barriers docs are included in kernel
> > docs build since commit e40573a43d163a ("docs: put atomic*.txt and
> > memory-barriers.txt into the core-api book") as a wrapper stub for
> > corresponding uncoverted txt docs. Let's turn them into full-fledged reST docs. 
> > 
> > Bagas Sanjaya (4):
> >   Documentation: memory-barriers: Convert to reST format
> >   Documentation: atomic_bitops: Convert to reST format
> >   Documentation: atomic_t: Convert to reST format
> >   Documentation: atomic_bitops, atomic_t, memory-barriers: Link to
> >     newly-converted docs  
> 
> NAK
> 
> If these are merged I will no longer touch / update these files.

One way a human discovers why something is the way it is, is to change it,
and see what the fallout is for that change.

  ;-)

-- Steve

On Thu, Jul 17, 2025 at 12:55:54PM +0200, Peter Zijlstra wrote:
> On Thu, Jul 17, 2025 at 03:06:13PM +0700, Bagas Sanjaya wrote:
> > Bagas Sanjaya (4):
> >   Documentation: memory-barriers: Convert to reST format
> >   Documentation: atomic_bitops: Convert to reST format
> >   Documentation: atomic_t: Convert to reST format
> >   Documentation: atomic_bitops, atomic_t, memory-barriers: Link to
> >     newly-converted docs
> 
> NAK
> 
> If these are merged I will no longer touch / update these files.

Why? Do you mean these docs should be kept as-is (not converted)? Jon wrote
in e40573a43d163a that the conversion were opposed but AFAIK I can't find
the rationale on lore.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

On 17/07/2025 13:26, Bagas Sanjaya wrote:
> On Thu, Jul 17, 2025 at 12:55:54PM +0200, Peter Zijlstra wrote:
>> On Thu, Jul 17, 2025 at 03:06:13PM +0700, Bagas Sanjaya wrote:
>>> Bagas Sanjaya (4):
>>>    Documentation: memory-barriers: Convert to reST format
>>>    Documentation: atomic_bitops: Convert to reST format
>>>    Documentation: atomic_t: Convert to reST format
>>>    Documentation: atomic_bitops, atomic_t, memory-barriers: Link to
>>>      newly-converted docs
>>
>> NAK
>>
>> If these are merged I will no longer touch / update these files.
> 
> Why? Do you mean these docs should be kept as-is (not converted)? Jon wrote
> in e40573a43d163a that the conversion were opposed but AFAIK I can't find
> the rationale on lore.

Here's one:

https://lore.kernel.org/all/20200806064823.GA7292@infradead.org/


Vegard

On Thu, Jul 17, 2025 at 01:56:12PM +0200, Vegard Nossum wrote:
> On 17/07/2025 13:26, Bagas Sanjaya wrote:
> > On Thu, Jul 17, 2025 at 12:55:54PM +0200, Peter Zijlstra wrote:
> > > On Thu, Jul 17, 2025 at 03:06:13PM +0700, Bagas Sanjaya wrote:
> > > > Bagas Sanjaya (4):
> > > >    Documentation: memory-barriers: Convert to reST format
> > > >    Documentation: atomic_bitops: Convert to reST format
> > > >    Documentation: atomic_t: Convert to reST format
> > > >    Documentation: atomic_bitops, atomic_t, memory-barriers: Link to
> > > >      newly-converted docs
> > > 
> > > NAK
> > > 
> > > If these are merged I will no longer touch / update these files.
> > 
> > Why? Do you mean these docs should be kept as-is (not converted)? Jon wrote
> > in e40573a43d163a that the conversion were opposed but AFAIK I can't find
> > the rationale on lore.
> 
> Here's one:
> 
> https://lore.kernel.org/all/20200806064823.GA7292@infradead.org/

OK, thanks!

-- 
An old man doll... just what I always wanted! - Clara