Re: [PATCH v2 00/12] Convert some DT documentation files to ReST

From
Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date
2020-03-03 17:07:08
Also in
linux-devicetree, lkml
Reply to
Mauro Carvalho Chehab, 2020-03-03
Em Tue, 3 Mar 2020 18:01:09 +0100
Mauro Carvalho Chehab [off-list ref] escreveu:
Em Tue, 3 Mar 2020 10:20:25 -0600
Rob Herring [off-list ref] escreveu:
quoted
On Tue, Mar 3, 2020 at 1:09 AM Mauro Carvalho Chehab
[off-list ref] wrote:  
quoted
Em Mon, 2 Mar 2020 12:35:54 -0700
Jonathan Corbet [off-list ref] escreveu:
   
quoted
On Mon,  2 Mar 2020 08:59:25 +0100
Mauro Carvalho Chehab [off-list ref] wrote:
   
quoted
While most of the devicetree stuff has its own format (with is now being
converted to YAML format), some documents there are actually
describing the DT concepts and how to contribute to it.

IMHO, those documents would fit perfectly as part of the documentation
body, as part of the firmare documents set.

This patch series manually converts some DT documents that, on my
opinion, would belong to it.    
Did you consider putting this stuff into the firmware-guide while you were
at it?  It's not a perfect fit, I guess, but it doesn't seem too awkward
either.    
I placed it just below the firmware-guide at the main index file.

I have split thoughts about moving the files to there, though. From
one side, it may fit better from the PoV of organizing the documentation.

From other side, newcomers working with DT may expect looking at the
text files inside Documentation/devicetree/.

Maybe I could add an extra patch at the end of this series with the
move, adding a "RFC" on his title. This way, we can better discuss it,
and either merge the last one or not depending on the comments.    
Keep in mind that we generate a standalone DT only tree[1] with the
documentation, dts files and headers. So things should be structured
such that all the DT documentation could be built by itself without
dependencies on the 'kernel documentation'. I'm not asking for that to
be done in this series, but just don't do anything to make that
harder. I don't *think* have, but just want to make sure that's clear.  
So, I guess it is better to keep the .rst files under Documentation/devicetree,
instead of moving them to Documentation/firmware-guide.

Well, if moved, I guess it would be easy to modify the scripts that produce
the documentation to also parse something a new directory inside
Documentation/firmware-guide.
quoted
  
quoted
quoted
It also seems like it would be good to CC the devicetree folks, or at
least the devicetree mailing list?    
I was wondering what happened to the cover letter on v2...
  
quoted
Yeah, that would make sense. I'm using get-maintainers script to
prepare the c/c list, as it is simply too much work to find the
right maintainers by hand, for every single patch.

I just noticed today that there's just *one entry* at MAINTAINERS
file for Documentation/devicetree, and that points to you:

        DOCUMENTATION
        M:      Jonathan Corbet [off-list ref]
        L:      linux-doc@vger.kernel.org
        S:      Maintained
        F:      Documentation/
        F:      scripts/documentation-file-ref-check
        F:      scripts/kernel-doc
        F:      scripts/sphinx-pre-install
        X:      Documentation/ABI/
        X:      Documentation/firmware-guide/acpi/
        X:      Documentation/devicetree/    
You mean doesn't point to Jon as 'X' is exclude. You missed this entry:

OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS
M:      Rob Herring [off-list ref]
M:      Mark Rutland [off-list ref]
L:      devicetree@vger.kernel.org
T:      git git://git.kernel.org/pub/scm/linux/kernel/git/robh/linux.git
Q:      http://patchwork.ozlabs.org/project/devicetree-bindings/list/
S:      Maintained
F:      Documentation/devicetree/
F:      arch/*/boot/dts/
F:      include/dt-bindings/  
Yeah, I remember I saw something like the above in the past. However,
I'm not seeing this entry at the MAINTAINERS file at next-20200303 anymore.

Did someone removed such entry?
Sorry, false alarm. 

It is there at next. 

I guess it is time for call it a day.

That doesn't explain why I didn't add DT ML to the c/c. I'll try to 
verify what's going on tomorrow.

Regards,
Mauro
Thread (33 messages) 33 messages, 7 authors, last reply 2020-03-05
Keyboard shortcuts
hback out one level
jnext message in thread / next series-diff position
kprevious message in thread / previous series-diff position
ldrill in
Escclose help / fold thread tree
?toggle this help