Mauro Carvalho Chehab [Sat, 23 Jul 2016 10:55:59 +0000 (07:55 -0300)]
Merge branch 'docs-next' of git://git.lwn.net/linux into topic/docs-next
* 'docs-next' of git://git.lwn.net/linux:
doc-rst: kernel-doc: fix handling of address_space tags
Revert "doc/sphinx: Enable keep_warnings"
doc-rst: kernel-doc directive, fix state machine reporter
docs: deprecate kernel-doc-nano-HOWTO.txt
doc/sphinx: Enable keep_warnings
Documentation: add watermark_scale_factor to the list of vm systcl file
kernel-doc: Fix up warning output
docs: Get rid of some kernel-documentation warnings
Mauro Carvalho Chehab [Fri, 22 Jul 2016 14:46:36 +0000 (11:46 -0300)]
doc-rst: kernel-doc: fix handling of address_space tags
The RST cpp:function handler is very pedantic: it doesn't allow any
macros like __user on it:
Documentation/media/kapi/dtv-core.rst:28: WARNING: Error when parsing function declaration.
If the function has no return type:
Error in declarator or parameters and qualifiers
Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8]
ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
--------^
If the function has a return type:
Error in declarator or parameters and qualifiers
If pointer to member declarator:
Invalid definition: Expected '::' in pointer to member (function). [error at 37]
ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
-------------------------------------^
If declarator-id:
Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102]
ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
------------------------------------------------------------------------------------------------------^
So, we have to remove it from the function prototype.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 20 Jul 2016 22:56:21 +0000 (16:56 -0600)]
Revert "doc/sphinx: Enable keep_warnings"
This reverts commit
47d6d752b9e20dbe8a2acd22e887be81a6f39de9.
Commit
f42ddca7bebc (doc-rst: kernel-doc directive, fix state machine
reporter) from Marcus Heiser provides a better fix, so this configuration
change is no longer needed.
Markus Heiser [Wed, 20 Jul 2016 10:38:58 +0000 (12:38 +0200)]
doc-rst: kernel-doc directive, fix state machine reporter
Add a reporter replacement that assigns the correct source name and line
number to a system message, as recorded in a ViewList.
[1] http://mid.gmane.org/CAKMK7uFMQ2wOp99t-8v06Om78mi9OvRZWuQsFJD55QA20BB3iw@mail.gmail.com
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 20 Jul 2016 22:43:41 +0000 (16:43 -0600)]
docs: deprecate kernel-doc-nano-HOWTO.txt
Now that the new Sphinx world order is taking over, the information in
kernel-doc-nano-HOWTO.txt is outmoded. I hate to remove it altogether,
since it's one of those files that people expect to find. But we can add a
warning and fix all the other pointers to it.
Reminded-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Daniel Vetter [Tue, 19 Jul 2016 11:42:54 +0000 (13:42 +0200)]
doc/sphinx: Enable keep_warnings
Unfortunately warnings generated after parsing in sphinx can end up
with entirely bogus files and line numbers as sources. Strangely for
outright errors this is not a problem. Trying to convert warnings to
errors also doesn't fix it.
The only way to get useful output out of sphinx to be able to root
cause the error seems to be enabling keep_warnings, which inserts
a System Message into the actual output. Not pretty at all, but I
don't really want to fix up core rst/sphinx code, and this gets the job
done meanwhile.
Cc: Markus Heiser <markus.heiser@darmarit.de>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Hans Verkuil [Tue, 19 Jul 2016 09:26:13 +0000 (06:26 -0300)]
[media] doc-rst: cec: update documentation
Update and expand the CEC documentation. Especially w.r.t. non-blocking
mode.
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Tue, 19 Jul 2016 15:35:08 +0000 (12:35 -0300)]
[media] doc-rst: backward compatibility with older Sphinx versions
Sphinx is really evil when an older version finds an extra
attribute for the :toctree: tag: it simply ignores everything
and produce documents without any chapter inside!
As we're now using tags available only on Sphinx 1.4.x, we
need to use some creative ways to add a title before the
table of contents. Do that by using a css class.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 18:01:20 +0000 (15:01 -0300)]
[media] doc-rst: better name the media books
The titles at the media books were misleading, and some books
were not numbered.
Rename the kAPI book to better reflect its contents, be more
consistent on the initial rst file for each book and better
name them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 17:46:07 +0000 (14:46 -0300)]
[media] doc-rst: fix media kAPI documentation
I ended by adding twice each media header, because I saw some
missing stuff at the documents. It seems it was my mistake,
as everything seems to be there.
So, remove those extra stuff, to avoid duplicating the
documentation of the functions.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 17:28:58 +0000 (14:28 -0300)]
[media] get rid of Documentation/video4linux/lifeview.txt
Move the contents of this file to bttv.rst and saa7134.rst.
With that, we can finally remove Documentation/video4linux.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 17:18:10 +0000 (14:18 -0300)]
[media] cx88.rst: add contents of hauppauge-wintv-cx88-ir.txt
Import the contents of hauppauge-wintv-cx88-ir.txt, after
converted to ReST into cx88.rst file.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 17:10:40 +0000 (14:10 -0300)]
[media] cx88.rst: add contents from not-in-cx2388x-datasheet.txt
There are some information about missing/wrong documentation at
cx231xx datasheet. Add it to the cx88 chapter.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 17:07:10 +0000 (14:07 -0300)]
[media] cx2341x.rst: add contents of README.vbi
Finally, adds the content of README.vbi at cx2341x.rst after
its conversion to ReST format.
Now, add information about this chipset and its driver is
inside a single chapter at the media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 17:01:51 +0000 (14:01 -0300)]
[media] cx2341x: add contents of README.hm12
The README.hm12 file describes the proprietary format used
by this driver for raw format, called HM12. Add its description
at the document, after converted to ReST.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 16:56:43 +0000 (13:56 -0300)]
[media] cx2341x.rst: add contents of fw-osd-api.txt
Convert it to ReST format and add to cx2341x.rst file.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 16:45:27 +0000 (13:45 -0300)]
[media] cx2341x.rst: add the contents of fw-upload.txt
Add the contents of fw-upload.txt, after converting it to
ReST format.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 16:42:17 +0000 (13:42 -0300)]
[media] cx2341x.rst: add contents of fw-memory.txt
Convert the content to ReST and add it at the cx231xx.rst
file.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 16:32:53 +0000 (13:32 -0300)]
[media] cx2341x.rst: add contents of fw-dma.txt
Add the contents of fw-dma.txt, converted to ReST, and
drop the old file.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 16:26:30 +0000 (13:26 -0300)]
[media] cx2341x.rst: add the contents of fw-calling.txt
Convert it to ReST and add its contents at this file.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 15:48:36 +0000 (12:48 -0300)]
[media] cx2341x.rst: Add the contents of fw-encoder-api.txt
Convert its contents to ReST and add to cx2341x.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 14:08:24 +0000 (11:08 -0300)]
[media] cx2341x.rst: add fw-decoder-registers.txt content
Convert the contents of fw-decoder-registers.txt to ReST and
add it to cx2341x.rst file.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Jerome Marchand [Tue, 12 Jul 2016 10:05:59 +0000 (12:05 +0200)]
Documentation: add watermark_scale_factor to the list of vm systcl file
Commit
795ae7a0de6b ("mm: scale kswapd watermarks in proportion to
memory") properly added the description of the new knob to
Documentation/sysctl/vm.txt, but forgot to add it to the list of files
in /proc/sys/vm. Let's fix that.
Signed-off-by: Jerome Marchand <jmarchan@redhat.com>
Acked-by: Johannes Weiner <hannes@cmpxchg.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 14:03:54 +0000 (11:03 -0300)]
[media] doc-rst: start adding documentation for cx2341x
move the contents of fw-decoder-api.txt to cx2341x and
convert it to ReST file, adding it to media/v4l-drivers
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 13:38:35 +0000 (10:38 -0300)]
[media] doc-rst: add documentation for tuners
Convert bttv/Tuners to ReST and add it to the media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 13:30:59 +0000 (10:30 -0300)]
[media] doc-rst: add documentation for bttv driver
Convert it to ReST and add it to media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 13:04:48 +0000 (10:04 -0300)]
[media] doc-rst: move bttv documentation to bttv.rst file
There were several files under Documentation/video4linux/bttv.
Instead of simply copying them to the rst folder, I opted to
merge into a single document and adjust the headers to
adjust the section levels and fix the cards tables.
There are two exceptions on the merge:
- The Tuners were renamed as a separate document, as they
describe a separate driver;
- I removed the PROBLEMS section. It describes problems with
the very first generation of 3D boards (Mistique/S3).
It sounds very unlikely that someone would still need to
install a bttv board on such hardware. Also, it is not
very well written, IMHO.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Daniel Vetter [Fri, 15 Jul 2016 08:19:30 +0000 (10:19 +0200)]
kernel-doc: Fix up warning output
While trying to make gpu docs warning free I stumbled over one output
which wasn't following proper compiler error output standards. Fix it
up for more quickfix awesomeness.
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 01:34:51 +0000 (22:34 -0300)]
[media] v4l-with-ir.rst: update it to reflect the current status
This document were really old. Update it to reflect the current
status of the IR drivers for TV.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 01:11:47 +0000 (22:11 -0300)]
[media] doc-rst: add documentation about IR on V4L boards
This section is outdated, but let's add it, after converting
to ReST, and then fix it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 01:07:30 +0000 (22:07 -0300)]
[media] doc-rst: add vivid documentation
Convert it to ReST and add to media/v4l-drivers book.
As the sections here (and on other docs) are numbered,
let's also make this book auto-numbered.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Mon, 18 Jul 2016 00:29:09 +0000 (21:29 -0300)]
[media] doc-rst: add documentation for Zoran driver
Convert it to ReST and add to media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 23:50:45 +0000 (20:50 -0300)]
[media] doc-rst: add documentation for uvcvideo
Convert it to ReST and add to media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 23:44:13 +0000 (20:44 -0300)]
[media] doc-rst: add soc-camera documentation
Convert it to ReST format and add it at media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 23:32:28 +0000 (20:32 -0300)]
[media] doc-rst: add documentation for si476x
Convert it to ReST and add to media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 23:07:16 +0000 (20:07 -0300)]
[media] doc-rst: add documentation for si4713
Convert it to ReST and add it to the media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 22:52:48 +0000 (19:52 -0300)]
[media] doc-rst: add documentation for si470x
Convert it to ReST and add to media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 22:43:22 +0000 (19:43 -0300)]
[media] doc-rst: add sh_mobile_ceu_camera crop documentation
Convert it to ReST and add it to media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 22:26:43 +0000 (19:26 -0300)]
[media] doc-rst: add documentation for saa7134
Convert it to ReST and add to the media/v4l-device book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 22:03:53 +0000 (19:03 -0300)]
[media] doc-rst: add documentation for radiotrack
Convert it to ReST and add it to the media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 21:52:53 +0000 (18:52 -0300)]
[media] doc-rst: add pxa_camera documentation
Convert pxa_camera to ReST format and add it to the
media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 21:45:25 +0000 (18:45 -0300)]
[media] doc-rst: add documentation for pvrusb2
Convert pvrusb2 documentation to ReST file and removed the note
about an html version of the documentation, as it is not
shipped inside the Kernel.
Add it to media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 21:38:01 +0000 (18:38 -0300)]
[media] doc-rst: add omap4_camera documentation
Convert the omap4_camera documentation to ReST and add it to
the media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 21:31:51 +0000 (18:31 -0300)]
[media] doc-rst: add omap3isp documentation
Convert omap3isp documentation to ReST and add it to the
media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 21:20:51 +0000 (18:20 -0300)]
[media] doc-rst: add meye documentation
Convert the meye documentation to rst and add it to the
media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 21:13:46 +0000 (18:13 -0300)]
[media] doc-rst: Add ivtv documentation
Convert ivtv documentation to rst, update the links there
and add to media/v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 20:57:31 +0000 (17:57 -0300)]
[media] doc-rst: add documentation for fimc driver
Convert the document to rst and add it to the v4l-drivers
book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 20:49:05 +0000 (17:49 -0300)]
[media] doc-rst: add davinci-vpbe documentation
Convert it to rst format and add it to the v4l-drivers book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 20:44:45 +0000 (17:44 -0300)]
[media] cx88.rst: Update the documentation
This doc is outdated, and contains information that it is not
true anymore. Update it to reflect the changes that this
driver suffered since I started working on it.
While here, also update Gerd's name.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 20:28:40 +0000 (17:28 -0300)]
[media] doc-rst: Add cx88 documentation to media book
Convert the cx88 documentation to rst and add it to the v4l-devices
book
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 20:20:26 +0000 (17:20 -0300)]
[media] doc-rst: add documentation for cpia2 driver
Convert the documentation to rst, merge the two files and
add to the index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 20:05:20 +0000 (17:05 -0300)]
[media] doc-rst: add Zoran zr364xx documentation
Convert the documentation to rst and add it to the book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 19:45:05 +0000 (16:45 -0300)]
[media] doc-rst: add gspca cardlist
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 19:32:50 +0000 (16:32 -0300)]
[media] doc-rst: convert cafe_ccic file to rst format
This file is almost ok, but it needs chapter/sections
and a code-block.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 19:32:38 +0000 (16:32 -0300)]
[media] doc-rst: convert fourcc to rst format
Fix fourcc for it to be correcly parsed by Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 19:03:31 +0000 (16:03 -0300)]
[media] doc-rst: Move v4l docs to media/v4l-drivers
Move V4L documentation files to media/v4l-drivers. Those aren't
core stuff, so they don't fit at the kAPI document.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Jonathan Corbet [Mon, 18 Jul 2016 01:24:02 +0000 (19:24 -0600)]
docs: Get rid of some kernel-documentation warnings
Sphinx wants to interpret all literal blocks as being in the chosen
language and complains when an attempt to parse a block fails.
kernel-documentation.rst has a few blocks that are not in C; make that
explicit to shut down the associated warnings.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 19:00:30 +0000 (16:00 -0300)]
doc-rst: add v4l-drivers to index file
Adds documentation for V4L drivers.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 18:58:51 +0000 (15:58 -0300)]
[media] doc-rst: Convert videobuf documentation to ReST
The videobuf documentation is almost at rst format: we
just needed to add titles and add some code-blocks there
and that's it.
Also, add a notice that this framework is deprecated.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 18:49:56 +0000 (15:49 -0300)]
[media] doc-rst: move videobuf documentation to media/kapi
This document describes a kapi framework. Move it to the right
place.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 18:25:27 +0000 (15:25 -0300)]
[media] doc-rst: do a poor man's conversion of v4l2-framework
Make Sphinx happy with v4l2-framework.rst by putting all C
code inside code-block.
Please note that this is a poor man ReST conversion, as several
of those blocks should actually be converted to use :cpp:func:,
pointing to the kAPI auto-generated documentation.
The problem is that we currently lack kernel-doc documentation
for most of the stuff described there.
So, let's do a poor man's conversion. We should later address
this.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 18:19:48 +0000 (15:19 -0300)]
[media] doc-rst: move framework docs to kAPI documentation
Those documentation are part of the kAPI one. Move to the right
place.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 18:04:19 +0000 (15:04 -0300)]
[media] doc-rst: Remove deprecated API.html document
This document points to some old stuff. Just remove it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 17:13:28 +0000 (14:13 -0300)]
[media] doc-rst: move cardlists to media/v4l-drivers
Convert the cardlists to ReST format and move them to
Documentation/media/v4l-drivers/
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 17:08:12 +0000 (14:08 -0300)]
[media] extract_xc3028.pl: move it to scripts/dir
This doesn't belong at documentation. Move it to scripts.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 16:58:36 +0000 (13:58 -0300)]
[media] add DVB documentation to Sphinx
Now that all DVB files got converted, add it to Sphinx
build.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 16:57:24 +0000 (13:57 -0300)]
[media] doc-rst: convert udev chapter to rst
This chapter is outdated. I almost removed, but, as we're lacking
documentation about how to make DVB devices persistent, I opted,
instead, to keep it, and add a note about that.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 16:49:09 +0000 (13:49 -0300)]
[media] doc-rst: convert ttusb-dev to rst
There are some things that needed to be done to convert
it to ReST. Also, there are some obsolete info there
related to Kernels 2.4 and 2.6. Update them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 16:43:54 +0000 (13:43 -0300)]
[media] doc-rst: Convert technisat document to ReST
This document need some changes to be properly parsed by
Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 16:34:01 +0000 (13:34 -0300)]
[media] doc-rst: add opera-firmware.rst to DVB docs
This file is shown OK with ReST. Yet, as we changed the
place where the get_dvb_firmware script is, we need to
update it.
While here, move the author's name to the beginning of the
file.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 16:30:21 +0000 (13:30 -0300)]
[media] doc-rst: Convert lmedm04 to rst format
This file was missing a name for the index, and weren't
using any markup language. Make it looks better and
convert to ReST.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 16:21:49 +0000 (13:21 -0300)]
[media] doc-rst: convert DVB FAQ to ReST format
Convert the DVB FAQ to ReST format and add a note that this is
outdated.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 16:17:41 +0000 (13:17 -0300)]
[media] doc-rst: Convert dvb-usb to ReST format
This file is not on any markup language. Convert it to
ReST format.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 15:59:35 +0000 (12:59 -0300)]
[media] doc-rst: Convert contributors list to ReST
The contributors list needs some adjustments to be properly
formatted.
Also, this list has not been updated for a while. So, add a
notice about that.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 15:48:43 +0000 (12:48 -0300)]
[media] doc-rst: Convert ci.txt to a rst file
The old ci.txt file had a very peculiar format, with doesn't
match any markup language I know. Change it to be on ReST
format, for it to be parsed by Sphinx.
Also, as this is an old document, add a note about it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 15:33:31 +0000 (12:33 -0300)]
[media] doc-rst: convert cards to rst format
This file is using a markup-like language, but it is not quite
ReST. Convert it, and add a note pointing to the Wiki page with
the known supported hardware devices.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 15:25:43 +0000 (12:25 -0300)]
[media] doc-rst: convert bt8xx doc to rst
This document almost follows a markup language, but it is
not ReST. Fix it to be handled by Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 15:13:21 +0000 (12:13 -0300)]
[media] doc-rst: Fix format of avermedia.rst
This file is almost at the ReST format, but some things need
to be fixed for it to be parsed.
Also, the documentation there is old. So, add a notice about
that.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 15:05:21 +0000 (12:05 -0300)]
[media] doc-rst: move DVB introduction to a separate file
Instead of keeping the introduction together with the
index, move it to a separate file, and add it via toctree
at the index.
The information there are outdated, so update it to point
to the right links.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 14:34:58 +0000 (11:34 -0300)]
[media] doc-rst: move DVB avulse docs to Documentation/media
There are several documentation stuff under Documentation/dvb.
Move them to Documentation/media/dvb-drivers and rename them to
rst, as they'll soon be converted to rst files.
No changes at the documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 14:25:37 +0000 (11:25 -0300)]
[media] doc-rst: Fix conversion for dvb-core.rst
The conversion from DocBook required some fixes:
- Now, the C files with the exported symbols also need to be
added. So, all headers need to be included twice: one to
get the structs/enums/.. and another one for the functions;
- Notes should use the ReST tag, as kernel-doc doesn't
recognizes it anymore;
- Identation needs to be fixed, as ReST uses it to identify
when a format "tag" ends.
- Fix the cross-references at the media controller description.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 12:18:03 +0000 (09:18 -0300)]
[media] doc-rst: Fix conversion for MC core functions
There were lots of issues at the media controller side,
after the conversion:
- Some documentation at the header files weren't using the
kernel-doc start block;
- Now, the C files with the exported symbols also need to be
added. So, all headers need to be included twice: one to
get the structs/enums/.. and another one for the functions;
- Notes should use the ReST tag, as kernel-doc doesn't
recognizes it anymore;
- Identation needs to be fixed, as ReST uses it to identify
when a format "tag" ends.
- Fix the cross-references at the media controller description.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 11:44:08 +0000 (08:44 -0300)]
[media] doc-rst: Fix conversion for v4l2 core functions
The conversion from DocBook lead into some conversion issues,
basically due to the lack of proper support at kernel-doc.
So, address them:
- Now, the C files with the exported symbols also need to be
added. So, all headers need to be included twice: one to
get the structs/enums/.. and another one for the functions;
- Notes should use the ReST tag, as kernel-doc doesn't
recognizes it anymore;
- Identation needs to be fixed, as ReST uses it to identify
when a format "tag" ends.
- kernel-doc doesn't escape things like *pointer, so we
need to manually add a escape char before it.
- On some cases, kernel-doc conversion requires violating
the 80-cols, as otherwise it won't properly parse the
source code.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 12:16:57 +0000 (09:16 -0300)]
[media] doc-rst: Fix issues with RC documentation
The kernel-doc script is now broken if it doesn't find all
exported symbols documented.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 11:22:23 +0000 (08:22 -0300)]
[media] doc-rst: split media_drivers.rst into one file per API type
Just like the uAPI book is split into parts, let's split the
kAPI documentation. That should make easier to maintain, and
will split the final documentation into smaller html files.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 11:15:08 +0000 (08:15 -0300)]
[media] doc-rst: media_drivers.rst: Fix paragraph headers for MC
Fix the paragraph identation for the media controller
headers.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Sun, 17 Jul 2016 10:20:06 +0000 (07:20 -0300)]
[media] doc-rst: Convert media API to rst
Move the contents of the media section at
DocBooks/DocBook/device-drivers.tmpl to a new ReST book.
For now, the contents is kept as-is. Next patches will fix
the warnings and add cross-references that were removed due to
the conversion.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Fri, 15 Jul 2016 10:42:08 +0000 (07:42 -0300)]
doc-rst: Fix compilation of the pdf docbook
The rst2pdf tool is a very broken toolchain, with is not capable
of parsing complex documents. As such, it doesn't build the
media book, failing with:
[ERROR] pdfbuilder.py:130 too many values to unpack
(using rst2pdf version 0.93.dev-r0 and Sphinx version 1.4.5)
So, make it build only the books we know that are safe to build.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
--
Btw, with the standard Sphinx version shipped on Fedora 24 (Sphinx
1.3.1), rst2pdf doesn't build even the simple kernel-documentation,
failing with this error:
writing Kernel... [ERROR] pdfbuilder.py:130 list index out of range
This is a known bug:
https://github.com/sphinx-doc/sphinx/issues/1844
So, maybe we should just disable pdf generation from RST for good,
as I suspect that maintaining it with a broken toolchain will be a
big headache.
Mauro Carvalho Chehab [Fri, 15 Jul 2016 10:33:47 +0000 (07:33 -0300)]
Merge branch 'docs-next' of git://git.lwn.net/linux into devel/docs-next
* 'docs-next' of git://git.lwn.net/linux:
doc-rst: add an option to ignore DocBooks when generating docs
workqueue: Fix a typo in workqueue.txt
Doc: ocfs: Fix typo in filesystems/ocfs2-online-filecheck.txt
Documentation/sphinx: skip build if user requested specific DOCBOOKS
Documentation: add cleanmediadocs to the documentation targets
Mauro Carvalho Chehab [Wed, 13 Jul 2016 14:45:48 +0000 (11:45 -0300)]
[media] docs-rst: Fix some typos
Those fixes came from patchs from Andrea for the old DocBook
documentation.
As we're removing it on Kernel 4.8, it doesn't make sense to
apply the original patches, but, as the typos were ported
to ReST, let's fix the issues there.
Suggested-by: Andrea Gelmini <andrea.gelmini@gelma.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Wed, 13 Jul 2016 13:50:34 +0000 (10:50 -0300)]
[media] doc-rst: increase depth of the main index
It is useful to have an index with all the book contents somewhere,
as it makes easier to seek for something. So, increase maxdepth
to 5 for the main index at the beginning of the book.
While here, remove the genindex content, as it is bogus.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Wed, 13 Jul 2016 13:22:38 +0000 (10:22 -0300)]
[media] doc-rst: fix an undefined reference
Documentation/media/uapi/cec/cec-ioc-dqevent.rst:43: WARNING: undefined label: cec_event_state_change (if the link has no caption the label must precede a section header)
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Hans Verkuil [Wed, 13 Jul 2016 11:48:54 +0000 (08:48 -0300)]
[media] doc-rst: improve CEC documentation
Lots of fixups relating to references.
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Wed, 13 Jul 2016 12:11:12 +0000 (09:11 -0300)]
[media] doc-rst: fix htmldocs build warnings
Fix those warnings:
Documentation/output/videodev2.h.rst:6: WARNING: undefined label: vidioc_unsubscribe_event (if the link has no caption the label must precede a section header)
Documentation/media/uapi/v4l/dev-overlay.rst:248: WARNING: Title underline too short.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Wed, 13 Jul 2016 11:43:30 +0000 (08:43 -0300)]
Revert "[media] docs-rst: escape [] characters"
This patch touches on places where it shouldn't: image
files and code examples. Also, it doesn't fix all array
occurrences.
So, let's revert it.
This reverts commit
ffbab694ede33c294e5864a5e0bf4d1474446a71.
Hans Verkuil [Tue, 12 Jul 2016 18:07:44 +0000 (15:07 -0300)]
[media] doc-rst: update CEC_RECEIVE
The timestamp field was split into rx_ts and tx_ts, and the rx/tx_status
fields were moved. Update the doc accordingly.
Also fix a bug that stated that a non-zero tx_status field signaled an
error. That's not true, since TX_STATUS_OK is 1, not 0.
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Tue, 12 Jul 2016 18:20:11 +0000 (15:20 -0300)]
[media] docs-rst: escape [] characters
Those characters are used for citations. Better to escape, to
avoid them to be misinterpreted.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Tue, 12 Jul 2016 18:15:23 +0000 (15:15 -0300)]
[media] doc-rst: use the right markup for footnotes
According with ReST spec, footnotes should be like:
[#name], and not [name]. So, change them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Hans Verkuil [Tue, 12 Jul 2016 14:39:37 +0000 (11:39 -0300)]
[media] vidioc-g-dv-timings.rst: document interlaced defines
Document V4L2_DV_PROGRESSIVE and V4L2_DV_INTERLACED and
fix missing references.
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Hans Verkuil [Tue, 12 Jul 2016 14:31:15 +0000 (11:31 -0300)]
[media] pixfmt-006.rst: add missing V4L2_YCBCR_ENC_SMPTE240M
Fix missing documentation, and its cross reference.
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
This page took 0.044344 seconds and 5 git commands to generate.