Unfortunately, captions are new on Sphinx for c blocks: it was
added only on version 1.3. Also, it were already bad enough
not being able to auto-numerate them.

So, let's give up and use, instead, titles before the examples.
Not much is lost, and, as a side track, we don't need to
numerate them anymore.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Now that the LIRC header was added, we can cross-reference it
and identify the documentation gaps.

There are lots of stuff missing there, but at least now we
can avoid the gap to increase.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Just like the other parts of the document, let's add the LIRC
header, as it is part of the API.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The lirc syscall documentation uses a very different and
simplified way than the rest of the media book. make it
closer. Still, there's just one page for all ioctls.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Some files start with an upper letter. Also, they have big
names. rename them.

No functional changes.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

There's no need to say: Table of Contents there. Also, this
generates a duplicated caption xref. So, remove, to use the
same format on every part.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Just like the other parts of the media book, group the MC
functions together on one chapter.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Within the old section hierarchy, all doc parts has been placed under
the introduction, e.g:

* Linux Media Infrastructure API
    + Introduction
        - Video for Linux API
        - Digital TV API
        - ...

With separating the introduction sibling to the other parts
we get a more common section hierarchy:

* Linux Media Infrastructure API
    + Introduction
    + Video for Linux API
    + Digital TV API
    + ...

BTW: compacting the intro text.

This patch is on top of media_tree/docs-next
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>

Better organize the contents of the CEC part, moving the
introduction to chapter 1, placing all ioctls at chapter 2
and numerating all chapters and items.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Adding the header file is interesting for several reasons:

1) It makes MC documentation consistend with other parts;
2) The header file can be used as a quick index to all API
   elements;
3) The cross-reference check helps to identify symbols that
   aren't documented.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

* topic/cec:
  [media] DocBook/media: add CEC documentation
  [media] s5p_cec: get rid of an unused var
  [media] move s5p-cec to staging
  [media] vivid: add CEC emulation
  [media] cec: s5p-cec: Add s5p-cec driver
  [media] cec: adv7511: add cec support
  [media] cec: adv7842: add cec support
  [media] cec: adv7604: add cec support
  [media] cec: add compat32 ioctl support
  [media] cec/TODO: add TODO file so we know why this is still in staging
  [media] cec: add HDMI CEC framework (api)
  [media] cec: add HDMI CEC framework (adapter)
  [media] cec: add HDMI CEC framework (core)
  [media] cec-funcs.h: static inlines to pack/unpack CEC messages
  [media] cec.h: add cec header
  [media] cec-edid: add module for EDID CEC helper functions
  [media] cec.txt: add CEC framework documentation
  [media] rc: Add HDMI CEC protocol handling
  Input: add HDMI CEC specific keycodes
  Input: add BUS_CEC type

Adding the header file is interesting for several reasons:

1) It makes MC documentation consistend with other parts;
2) The header file can be used as a quick index to all API
   elements;
3) The cross-reference check helps to identify symbols that
   aren't documented.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The function that replace references add a "\ " at the end of
references, to avoid the ReST markup parser to not identify
them as references. That works fine except for the end of lines,
as a sequence of { '\', ' ', '\n' } characters makes Sphinx
to ignore the end of line. So, strip those escape/spaces at the
end of lines.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Changesets:
	eaa0b96b ("[media] media: Add video statistics computation functions")
and
	1179aab1 ("[media] media: Add video processing entity functions")

added some new elements to the "media entity types" table at the
DocBook. We need to do the same at the reST version, in order to
keep it in sync with the DocBook version.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Use the same format as the other parts.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Adjust the widths and show error codes as constants.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

leaved content unchanged, only improved markup and references

* more man-like sections (add Name section)
* defined target for each stuct field description
* replace constant with ":ref:" to (field) description
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This is the reST migration of media's CEC part.  The migration is based
on media_tree's cec branch:

 https://git.linuxtv.org/media_tree.git

 c7169ad5 * cec media_tree/cec [media] DocBook/media: add CEC documentation
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Changeset 811c6d6a ("[media] V4L: fix the Z16 format definition")
fixed the definition for DocBook, but we need to replicate it
also to ReST.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Changeset 8c9f46095176 ("[media] DocBook: mention the memory type to
be set for all streaming I/O") updated the media DocBook to mention
the need of filling the memory types. We need to keep the ReST
doc updated to such change.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Commit 707e65831d3b("[media] DocBook: add dmabuf as streaming I/O
in VIDIOC_REQBUFS description") added DMABUF to reqbufs description,
but, as we're migrating to ReST markup, we need to keep it in sync
with the change.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The name of the subsystem is "media", and not "linux_tv". Also,
as we plan to add other stuff there in the future, let's
rename also the media uAPI book to media_uapi, to make it
clearer.

No functional changes.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

I suspect that this is a left over from Markus tests.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

To honor the:

  make O=dir [targets] Locate all output files in "dir"

* activate kernel-include directive
* export BUILDDIR=$(BUILDDIR)
* linux_tv: replace '.. include::' with '.. kernel-include:: $BUILDDIR/<foo.h.rst>'
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The kernel-include directive is needed to include the auto generated rst
content from a build (pre-) process. E.g. the linux_tv Makefile
generates intermediate reST-files from header files. Since there is a O=
option:

  make O=dir [targets] Locate all output files in "dir"

We need to include intermediate reST files from arbitrary (O=/tmp/foo)
locations:

The 'kernel-include' reST-directive is a replacement for the 'include'
directive. The 'kernel-include' directive expand environment variables
in the path name and allows to include files from arbitrary locations.

.. hint::

  Including files from arbitrary locations (e.g. from '/etc') is a
  security risk for builders. This is why the 'include' directive from
  docutils *prohibit* pathnames pointing to locations *above* the
  filesystem tree where the reST document with the include directive is
  placed.

Substrings of the form $name or ${name} are replaced by the value of
environment variable name. Malformed variable names and references to
non-existing variables are left unchanged.
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Include auto-generate reST header files. BTW fixed linux_tv/Makefile.
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Cleanup the Makefile and handle the V=1 flag and make it
to work when specifying an output directory with O=dir
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Remove most of ignore stuff for defines, pointing them to the
proper tables/sections.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

After checking that all enum fields are documented at the
corresponding table on the rst file, let's point to the
table, instead of ignore the symbols.

A few symbols are not meant to be documented, as they're
deprecated stuff. keep ignoring them.

One enum field is not documented. Either it is obsolete
or a documentation gap. So, produce warnings for it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The content of those macros are all declared at the v4l2-std-id
table. So, point to it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Now that the reference problems were solved, let's not
ignore anymore the pix formats, as all of them are already
documented.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Several references were not converted right. That's why
so many symbols were lost when parsing videodev2.h header.

Fix them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This file comes from the uAPI definitions for V4L2, with is dynamic
and updated on almost every Kernel version. So, this file
needs to be auto-updated, as otherwise the documentation will
become obsolete too early.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Add one extra escape character to avoid those warnings:
	Documentation/linux_tv/videodev2.h.rst:6: WARNING: Inline substitution_reference start-string without end-string.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

At videodev2.h, we have hundreds of symbols that don't
currently have a reference yet. Let's ignore for how, while
we don't improve those cross-refs.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

We should not let comments to mangle with the symbols
parsing. Unfortunately, videodev2.h has lots of those
in the middle of enums and structs. So, we need to improve
our parser to discard them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This file comes from the uAPI definition header, and
should be auto-generated, to be in sync with Kernel changes.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This file comes from the uAPI definition header, and
should be auto-generated, to be in sync with Kernel changes.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This file comes from the uAPI definition header, and
should be auto-generated, to be in sync with Kernel changes.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This is an auto-generated header. Remove the hardcoded one
and do the right thing here.

NOTE: this is a deprecated API. So, we won't make any
effort to try identifying the meaning of this obscure
API that is used only on a legacy driver.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>