Script to build the media documentation as if it were a single book

Script to build the media documentation as if it were a single book

[Mauro Carvalho Chehab]

Hi,

In order for the media documentation to match the upstream rules, it was
split for 5.7 into 3 different books. This makes total sense for upstream.

Yet, people may still want to see it as a single book. So, I wrote a small
script (see enclosed) that does that.

I'm using a variant of it to produce the documentation output available at:
	https://linuxtv.org/docs.php

(with is updated once per day).

Perhaps others could find this script useful. This script is under GPLv2,
but please notice that some media docs are under GFDL licensing.

Thanks,
Mauro


#!/bin/bash

git remote update
git reset --hard remotes/origin/$BRANCH

sed s,userspace-api/media,media/userspace-api, -i Documentation/Makefile

mkdir -p Documentation/media

cat <<END >Documentation/media/index.rst
.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.txt>

**Copyright** |copy| 1991-: LinuxTV Developers

================================
Linux Kernel Media Documentation
================================

.. toctree::
	:maxdepth: 4

        admin-guide/index
        driver-api/index
        userspace-api/index
END

rsync -vuza --delete Documentation/admin-guide/media/ Documentation/media/admin-guide
rsync -vuza --delete Documentation/driver-api/media/ Documentation/media/driver-api
rsync -vuza --delete Documentation/userspace-api/media/ Documentation/media/userspace-api

make SPHINXDIRS="media" htmldocs
make SPHINXDIRS="media" pdfdocs
make SPHINXDIRS="media" epubdocs

Re: Script to build the media documentation as if it were a single book

[Hans Verkuil]

On 14/04/2020 15:37, Mauro Carvalho Chehab wrote:
> Hi,
> 
> In order for the media documentation to match the upstream rules, it was
> split for 5.7 into 3 different books. This makes total sense for upstream.
> 
> Yet, people may still want to see it as a single book. So, I wrote a small
> script (see enclosed) that does that.
> 
> I'm using a variant of it to produce the documentation output available at:
> 	https://linuxtv.org/docs.php
> 
> (with is updated once per day).
> 
> Perhaps others could find this script useful. This script is under GPLv2,
> but please notice that some media docs are under GFDL licensing.
> 
> Thanks,
> Mauro
> 
> 
> #!/bin/bash
> 
> git remote update
> git reset --hard remotes/origin/$BRANCH
> 
> sed s,userspace-api/media,media/userspace-api, -i Documentation/Makefile
> 
> mkdir -p Documentation/media
> 
> cat <<END >Documentation/media/index.rst
> .. SPDX-License-Identifier: GPL-2.0
> 
> .. include:: <isonum.txt>
> 
> **Copyright** |copy| 1991-: LinuxTV Developers
> 
> ================================
> Linux Kernel Media Documentation
> ================================
> 
> .. toctree::
> 	:maxdepth: 4
> 
>         admin-guide/index
>         driver-api/index
>         userspace-api/index

Wouldn't it make more sense to have the userspace-api before the admin-guide?

Regards,

	Hans

> END
> 
> rsync -vuza --delete Documentation/admin-guide/media/ Documentation/media/admin-guide
> rsync -vuza --delete Documentation/driver-api/media/ Documentation/media/driver-api
> rsync -vuza --delete Documentation/userspace-api/media/ Documentation/media/userspace-api
> 
> make SPHINXDIRS="media" htmldocs
> make SPHINXDIRS="media" pdfdocs
> make SPHINXDIRS="media" epubdocs
> 

Re: Script to build the media documentation as if it were a single book

[Mauro Carvalho Chehab]

Em Thu, 16 Apr 2020 09:01:55 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 14/04/2020 15:37, Mauro Carvalho Chehab wrote:

> > ================================
> > Linux Kernel Media Documentation
> > ================================
> > 
> > .. toctree::
> > 	:maxdepth: 4
> > 
> >         admin-guide/index
> >         driver-api/index
> >         userspace-api/index  
> 
> Wouldn't it make more sense to have the userspace-api before the admin-guide?

There, I just placed them on alphabetic order.

But answering your question, that depends on the audience ;-)

-

Yet, assuming that we are doing a good job, I would expect a lot more
users than developers[1].

[1] Granted, there are lots of gaps there for it to be a generic guide
    to media subsystem. I'm planning to improve the admin-guide in order
    to make it more consistent and useful for media users.

The order there, IMHO, doesn't matter much, as someone accessing it from
LinuxTV.org would likely use this URL:

	https://linuxtv.org/docs.php

Side note: I need to add a pointer to the admin guide there - and at the
wiki pages.

Thanks,
Mauro

Re: Script to build the media documentation as if it were a single book

[Hans Verkuil]

On 16/04/2020 09:21, Mauro Carvalho Chehab wrote:
> Em Thu, 16 Apr 2020 09:01:55 +0200
> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> 
>> On 14/04/2020 15:37, Mauro Carvalho Chehab wrote:
> 
>>> ================================
>>> Linux Kernel Media Documentation
>>> ================================
>>>
>>> .. toctree::
>>> 	:maxdepth: 4
>>>
>>>         admin-guide/index
>>>         driver-api/index
>>>         userspace-api/index  
>>
>> Wouldn't it make more sense to have the userspace-api before the admin-guide?
> 
> There, I just placed them on alphabetic order.
> 
> But answering your question, that depends on the audience ;-)
> 
> -
> 
> Yet, assuming that we are doing a good job, I would expect a lot more
> users than developers[1].

If you want to see what it looks like with userspace-api on top:

https://hverkuil.home.xs4all.nl/spec/index.html

I think it makes more sense that way.

Regards,

	Hans

> 
> [1] Granted, there are lots of gaps there for it to be a generic guide
>     to media subsystem. I'm planning to improve the admin-guide in order
>     to make it more consistent and useful for media users.
> 
> The order there, IMHO, doesn't matter much, as someone accessing it from
> LinuxTV.org would likely use this URL:
> 
> 	https://linuxtv.org/docs.php
> 
> Side note: I need to add a pointer to the admin guide there - and at the
> wiki pages.
> 
> Thanks,
> Mauro
> 

Re: Script to build the media documentation as if it were a single book

[Mauro Carvalho Chehab]

Em Thu, 16 Apr 2020 09:29:45 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 16/04/2020 09:21, Mauro Carvalho Chehab wrote:
> > Em Thu, 16 Apr 2020 09:01:55 +0200
> > Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> >   
> >> On 14/04/2020 15:37, Mauro Carvalho Chehab wrote:  
> >   
> >>> ================================
> >>> Linux Kernel Media Documentation
> >>> ================================
> >>>
> >>> .. toctree::
> >>> 	:maxdepth: 4
> >>>
> >>>         admin-guide/index
> >>>         driver-api/index
> >>>         userspace-api/index    
> >>
> >> Wouldn't it make more sense to have the userspace-api before the admin-guide?  
> > 
> > There, I just placed them on alphabetic order.
> > 
> > But answering your question, that depends on the audience ;-)
> > 
> > -
> > 
> > Yet, assuming that we are doing a good job, I would expect a lot more
> > users than developers[1].  
> 
> If you want to see what it looks like with userspace-api on top:
> 
> https://hverkuil.home.xs4all.nl/spec/index.html
> 
> I think it makes more sense that way.

With the current content, I fully agree with you. However, take a look
at the RFC patch I just sent. It is just the start of something
(and it is not aligned yet with the latest Kconfig changes).

Anyway, my plan is to add something that a random media user could
find some useful information, and point to our Wiki pages where
it would make sense.

> 
> Regards,
> 
> 	Hans
> 
> > 
> > [1] Granted, there are lots of gaps there for it to be a generic guide
> >     to media subsystem. I'm planning to improve the admin-guide in order
> >     to make it more consistent and useful for media users.
> > 
> > The order there, IMHO, doesn't matter much, as someone accessing it from
> > LinuxTV.org would likely use this URL:
> > 
> > 	https://linuxtv.org/docs.php
> > 
> > Side note: I need to add a pointer to the admin guide there - and at the
> > wiki pages.
> > 
> > Thanks,
> > Mauro
> >   
> 



Thanks,
Mauro

Re: Script to build the media documentation as if it were a single book

[Hans Verkuil]

On 16/04/2020 09:55, Mauro Carvalho Chehab wrote:
> Em Thu, 16 Apr 2020 09:29:45 +0200
> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> 
>> On 16/04/2020 09:21, Mauro Carvalho Chehab wrote:
>>> Em Thu, 16 Apr 2020 09:01:55 +0200
>>> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
>>>   
>>>> On 14/04/2020 15:37, Mauro Carvalho Chehab wrote:  
>>>   
>>>>> ================================
>>>>> Linux Kernel Media Documentation
>>>>> ================================
>>>>>
>>>>> .. toctree::
>>>>> 	:maxdepth: 4
>>>>>
>>>>>         admin-guide/index
>>>>>         driver-api/index
>>>>>         userspace-api/index    
>>>>
>>>> Wouldn't it make more sense to have the userspace-api before the admin-guide?  
>>>
>>> There, I just placed them on alphabetic order.
>>>
>>> But answering your question, that depends on the audience ;-)
>>>
>>> -
>>>
>>> Yet, assuming that we are doing a good job, I would expect a lot more
>>> users than developers[1].  
>>
>> If you want to see what it looks like with userspace-api on top:
>>
>> https://hverkuil.home.xs4all.nl/spec/index.html
>>
>> I think it makes more sense that way.
> 
> With the current content, I fully agree with you. However, take a look
> at the RFC patch I just sent. It is just the start of something
> (and it is not aligned yet with the latest Kconfig changes).
> 
> Anyway, my plan is to add something that a random media user could
> find some useful information, and point to our Wiki pages where
> it would make sense.

But that's only useful for people who need to build their own kernel or do
other admin tasks. That's a small group and it is usually a one-off thing.

The vast majority is interested in the public APIs.

Regards,

	Hans

> 
>>
>> Regards,
>>
>> 	Hans
>>
>>>
>>> [1] Granted, there are lots of gaps there for it to be a generic guide
>>>     to media subsystem. I'm planning to improve the admin-guide in order
>>>     to make it more consistent and useful for media users.
>>>
>>> The order there, IMHO, doesn't matter much, as someone accessing it from
>>> LinuxTV.org would likely use this URL:
>>>
>>> 	https://linuxtv.org/docs.php
>>>
>>> Side note: I need to add a pointer to the admin guide there - and at the
>>> wiki pages.
>>>
>>> Thanks,
>>> Mauro
>>>   
>>
> 
> 
> 
> Thanks,
> Mauro
> 

Re: Script to build the media documentation as if it were a single book

[Mauro Carvalho Chehab]

Em Thu, 16 Apr 2020 10:06:28 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 16/04/2020 09:55, Mauro Carvalho Chehab wrote:
> > Em Thu, 16 Apr 2020 09:29:45 +0200
> > Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> >   
> >> On 16/04/2020 09:21, Mauro Carvalho Chehab wrote:  
> >>> Em Thu, 16 Apr 2020 09:01:55 +0200
> >>> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> >>>     
> >>>> On 14/04/2020 15:37, Mauro Carvalho Chehab wrote:    
> >>>     
> >>>>> ================================
> >>>>> Linux Kernel Media Documentation
> >>>>> ================================
> >>>>>
> >>>>> .. toctree::
> >>>>> 	:maxdepth: 4
> >>>>>
> >>>>>         admin-guide/index
> >>>>>         driver-api/index
> >>>>>         userspace-api/index      
> >>>>
> >>>> Wouldn't it make more sense to have the userspace-api before the admin-guide?    
> >>>
> >>> There, I just placed them on alphabetic order.
> >>>
> >>> But answering your question, that depends on the audience ;-)
> >>>
> >>> -
> >>>
> >>> Yet, assuming that we are doing a good job, I would expect a lot more
> >>> users than developers[1].    
> >>
> >> If you want to see what it looks like with userspace-api on top:
> >>
> >> https://hverkuil.home.xs4all.nl/spec/index.html
> >>
> >> I think it makes more sense that way.  
> > 
> > With the current content, I fully agree with you. However, take a look
> > at the RFC patch I just sent. It is just the start of something
> > (and it is not aligned yet with the latest Kconfig changes).
> > 
> > Anyway, my plan is to add something that a random media user could
> > find some useful information, and point to our Wiki pages where
> > it would make sense.  
> 
> But that's only useful for people who need to build their own kernel or do
> other admin tasks. That's a small group and it is usually a one-off thing.

Well, all Kernel developers need that. Also userspace developers that
may want to build test drivers. So, the ones potentially interested
on this chapter contains the group of people interested at the public
API.

Granted, once some Kernel developer gets familiar with the stuff 
contained there, the uAPI guide becomes a lot more interesting, but
this is true for any technical book:

at the beginning, the introductory chapters (with don't have much
details) are the more relevant ones, as they explain the basic concepts
that will be present at the rest of the book. Once you pass that, the
other chapters will be a lot more interesting, and those are the ones 
that people re-visit more often.

> 
> The vast majority is interested in the public APIs.
> 
> Regards,
> 
> 	Hans
> 
> >   
> >>
> >> Regards,
> >>
> >> 	Hans
> >>  
> >>>
> >>> [1] Granted, there are lots of gaps there for it to be a generic guide
> >>>     to media subsystem. I'm planning to improve the admin-guide in order
> >>>     to make it more consistent and useful for media users.
> >>>
> >>> The order there, IMHO, doesn't matter much, as someone accessing it from
> >>> LinuxTV.org would likely use this URL:
> >>>
> >>> 	https://linuxtv.org/docs.php
> >>>
> >>> Side note: I need to add a pointer to the admin guide there - and at the
> >>> wiki pages.
> >>>
> >>> Thanks,
> >>> Mauro
> >>>     
> >>  
> > 
> > 
> > 
> > Thanks,
> > Mauro
> >   
> 



Thanks,
Mauro