Skip to contentSkip to conversation

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

DISCUSSION Mauro Carvalho Chehab 2 participants 7 messages Apr 14, 2020 – Apr 16, 2020 Media (V4L/DVB)

lore
Share & tools
lore
#0 lore raw

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

#1 lore raw
Quoted 40 lines · 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
================================

Quoted 6 lines

.. 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

Quoted 10 lines

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

#2 lore raw

Em Thu, 16 Apr 2020 09:01:55 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 6 lines · Mauro Carvalho Chehab
Quoted 5 lines

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

Quoted 8 lines
Quoted 6 lines

.. 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

#3 lore raw
Quoted 18 lines · Mauro Carvalho Chehab

Em Thu, 16 Apr 2020 09:01:55 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 6 lines · Mauro Carvalho Chehab
Quoted 5 lines

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

Quoted 8 lines
Quoted 6 lines

.. 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?

Quoted 8 lines

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

Quoted 16 lines

[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

#4 lore raw

Em Thu, 16 Apr 2020 09:29:45 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 25 lines · Mauro Carvalho Chehab
Quoted 24 lines

Em Thu, 16 Apr 2020 09:01:55 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 6 lines · Mauro Carvalho Chehab
Quoted 5 lines

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

Quoted 8 lines
Quoted 6 lines

.. 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 ;-)

-

Quoted 8 lines
Quoted 2 lines

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.

Quoted 22 lines

Regards,

Hans

Quoted 16 lines

[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

#5 lore raw
Quoted 37 lines · Mauro Carvalho Chehab

Em Thu, 16 Apr 2020 09:29:45 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 25 lines · Mauro Carvalho Chehab
Quoted 24 lines

Em Thu, 16 Apr 2020 09:01:55 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 6 lines · Mauro Carvalho Chehab
Quoted 5 lines

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

Quoted 8 lines
Quoted 6 lines

.. 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 ;-)

-

Quoted 8 lines
Quoted 2 lines

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.

Quoted 7 lines

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

Quoted 29 lines
Quoted 23 lines

Regards,

Hans

Quoted 16 lines

[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

#6 lore raw

Em Thu, 16 Apr 2020 10:06:28 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 42 lines · Mauro Carvalho Chehab
Quoted 41 lines

Em Thu, 16 Apr 2020 09:29:45 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 25 lines · Mauro Carvalho Chehab
Quoted 24 lines

Em Thu, 16 Apr 2020 09:01:55 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 6 lines · Mauro Carvalho Chehab
Quoted 5 lines

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

Quoted 8 lines
Quoted 6 lines

.. 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 ;-)

-

Quoted 8 lines
Quoted 2 lines

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).

Quoted 6 lines
Quoted 3 lines

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.

Quoted 37 lines

The vast majority is interested in the public APIs.

Regards,

Hans

Quoted 29 lines
Quoted 23 lines

Regards,

Hans

Quoted 16 lines

[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