Eric Lee / smarc-fsl-linux-kernel

15 Mar, 2018

1 commit

  • 7f18a19b2   Documentation/sphinx: Fix Directive import error ... Browse Code »

    commit ff690eeed804f112242f9a0614eafdf559f9276a upstream.

    Sphinx 1.7 removed sphinx.util.compat.Directive so people
    who have upgraded cannot build the documentation. Switch to
    docutils.parsers.rst.Directive which has been available since
    docutils 0.5 released in 2009.

    Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694
    Co-developed-by: Takashi Iwai
    Acked-by: Jani Nikula
    Cc: stable@vger.kernel.org
    Signed-off-by: Matthew Wilcox
    Signed-off-by: Jonathan Corbet
    Signed-off-by: Greg Kroah-Hartman

    Matthew Wilcox
     

01 Sep, 2017

1 commit

  • 86c0f046a   Documentation/sphinx: fix kernel-doc decode for non-utf-8 locale ... Browse Code »

    On python3, Popen() universal_newlines=True converts the subprocess
    stdout to unicode text using a codec based on user preferences. Given
    LANG indicating ascii and utf-8 stdout from the subprocess, you'd get:

    WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno
    ../drivers/media/dvb-core/demux.h' processing failed with: 'ascii' codec can't
    decode byte 0xe2 in position 6368: ordinal not in range(128)

    Fix this by dropping universal_newlines=True and replacing the implicit
    LANG specific decode with an explicit utf-8 decode. This also gets rid
    of the annoying conditional code for python 2 vs. 3.

    Fixes: ba3501859354 ("Documentation/sphinx: fix kernel-doc extension on python3")
    Reference: http://mid.mail-archive.com/54c23e8e-89c0-5cea-0dcc-e938952c5642@infradead.org
    Reported-and-tested-by: Randy Dunlap
    Cc: Jonathan Corbet
    Cc: Mauro Carvalho Chehab
    Signed-off-by: Jani Nikula
    Signed-off-by: Jonathan Corbet

    Jani Nikula
     

24 Jul, 2017

1 commit

24 Jun, 2017

1 commit

16 May, 2017

1 commit

12 Apr, 2017

1 commit

  • 686b0d9bb   tmplcvt: make the tool more robust ... Browse Code »

    Currently, the script just assumes to be called at
    Documentation/sphinx/. Change it to work on any directory,
    and make it abort if something gets wrong.

    Also, be sure that both parameters are specified.

    That should avoid troubles like this:

    $ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
    sed: couldn't open file convert_template.sed: No such file or directory

    Signed-off-by: Mauro Carvalho Chehab
    Signed-off-by: Jonathan Corbet

    Mauro Carvalho Chehab
     

31 Mar, 2017

1 commit

09 Mar, 2017

1 commit

  • db6ccf23e   docs-rst: automatically convert Graphviz and SVG images ... Browse Code »

    This patch brings scalable figure, image handling and a concept to
    embed *render* markups:

    * DOT (http://www.graphviz.org)
    * SVG

    For image handling use the 'image' replacement::

    .. kernel-image:: svg_image.svg
    :alt: simple SVG image

    For figure handling use the 'figure' replacement::

    .. kernel-figure:: svg_image.svg
    :alt: simple SVG image

    SVG image example

    Embed *render* markups (or languages) like Graphviz's **DOT** is
    provided by the *render* directive.::

    .. kernel-render:: DOT
    :alt: foobar digraph
    :caption: Embedded **DOT** (Graphviz) code.

    digraph foo {
    "bar" -> "baz";
    }

    The *render* directive is a concept to integrate *render* markups and
    languages, yet supported markups:

    * DOT: render embedded Graphviz's **DOT**
    * SVG: render embedded Scalable Vector Graphics (**SVG**)

    Cc: Jani Nikula
    Cc: Laurent Pinchart
    Tested-by: Mauro Carvalho Chehab
    Tested-by: Daniel Vetter
    Signed-off-by: Daniel Vetter (v2 - v5)
    Signed-off-by: Markus Heiser (v1, v6)
    Signed-off-by: Jonathan Corbet

    Markus Heiser
     

19 Dec, 2016

1 commit

  • 217e2bfab   docs: sphinx-extensions: make rstFlatTable work with docutils 0.13 ... Browse Code »

    In docutils 0.13, the return type of get_column_widths method of the
    Table directive has changed [1], which breaks our flat-table directive
    and leads to a TypeError when trying to build the docs [2].

    This patch adds support for the new return type, while keeping support
    for older docutils versions too.

    [1] https://sourceforge.net/p/docutils/patches/120/
    [2] https://sourceforge.net/p/docutils/bugs/303/

    Signed-off-by: Dmitry Shachnev
    Cc: # 4.8.x-
    Signed-off-by: Jonathan Corbet

    Dmitry Shachnev
     

01 Dec, 2016

1 commit

  • c33966566   docs-rst: parse-headers.pl: cleanup the documentation ... Browse Code »

    Keeping both rst and in-file documentation in sync can be harsh.

    So, simplify the script's internal documntation to a bare minimum,
    and add a mention to the ReST file with its full documentation.

    This way, a quick help is still available at the command line,
    while the complete one is maintained at the ReST format.

    As we won't be using pad2rst anymore, do a cleanup at the ReST
    file.

    Signed-off-by: Mauro Carvalho Chehab
    Signed-off-by: Jonathan Corbet

    Mauro Carvalho Chehab
     

20 Nov, 2016

1 commit

20 Oct, 2016

1 commit

20 Sep, 2016

1 commit

  • 142a0e11b   Merge tag 'docs-next' of git://git.lwn.net/linux.git into patchwork ... Browse Code »

    Merge back from docs-next in order to get the cdomain extension.

    With such extension, the number of warnings when building docs
    in nitpick mode reduced from 22 to 2 warnings.

    * docs-next/docs-next:
    docs/driver-model: fix typo
    DMA-API-HOWTO: is no more
    doc-rst:c-domain: function-like macros arguments
    doc-rst:c-domain: fix sphinx version incompatibility
    Documentation/filesystems: Fixed typo
    docs: Don't format internal MPT docs
    docs: split up serial-interfaces.rst
    docs: Pull the HSI documentation together
    docs: Special-case function-pointer parameters in kernel-doc
    docs: make kernel-doc handle varargs properly
    x86: fix memory ranges in mm documentation
    documentation/scsi: Remove nodisconnect parameter
    doc: ioctl: Add some clarifications to botching-up-ioctls
    docs: split up the driver book
    Docs: sphinxify device-drivers.tmpl

    Mauro Carvalho Chehab
     

16 Sep, 2016

2 commits

09 Sep, 2016

2 commits

01 Sep, 2016

1 commit

  • b62b9d81a   docs: sphinx-extensions: add metadata parallel-safe ... Browse Code »

    The setup() function of a Sphinx-extension can return a dictionary. This
    is treated by Sphinx as metadata of the extension [1].

    With metadata "parallel_read_safe = True" a extension is marked as
    save for "parallel reading of source". This is needed if you want
    build in parallel with N processes. E.g.:

    make SPHINXOPTS=-j4 htmldocs

    will no longer log warnings like:

    WARNING: the foobar extension does not declare if it is safe for
    parallel reading, assuming it isn't - please ask the extension author
    to check and make it explicit.

    Add metadata to extensions:

    * kernel-doc
    * flat-table
    * kernel-include

    [1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadata

    Signed-off-by: Markus Heiser
    Tested-by: Mauro Carvalho Chehab
    Signed-off-by: Jonathan Corbet

    Markus Heiser
     

23 Aug, 2016

3 commits

  • 556aa6d5d   doc-rst: moved *duplicate* warnings to nitpicky mode ... Browse Code »

    Moved the *duplicate C object description* warnings for function
    declarations in the nitpicky mode. In nitpick mode, you can suppress
    those warnings (e.g. ioctl) with::

    nitpicky = True
    nitpick_ignore = [
    ("c:func", "ioctl"),
    ]

    See Sphinx documentation for the config values for ``nitpick`` and
    ``nitpick_ignore`` [1].

    With this change all the ".. cpp:function:: int ioctl(..)" descriptions
    (found in the media book) can be migrated to ".. c:function:: int
    ioctl(..)", without getting any warnings. E.g.::

    .. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp )

    .. c:function:: int ioctl( int fd, int request, struct cec_event *argp )

    The main effect, is that we get those *CPP-types* back into Sphinx's C-
    namespace and we need no longer to distinguish between c/cpp references,
    when we refer a function like the ioctl.

    [1] http://www.sphinx-doc.org/en/stable/config.html?highlight=nitpick#confval-nitpicky

    Signed-off-by: Markus Heiser
    Signed-off-by: Jonathan Corbet

    Markus Heiser
     
  • 2c645cd7c   doc-rst:c-domain: ref-name of a function declaration ... Browse Code »

    Add option 'name' to the "c:function:" directive. With option 'name'
    the ref-name of a function can be modified. E.g.::

    .. c:function:: int ioctl( int fd, int request )
    :name: VIDIOC_LOG_STATUS

    The func-name (e.g. ioctl) remains in the output but the ref-name
    changed from ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for
    this function is also changed to ``VIDIOC_LOG_STATUS`` and the function
    can now referenced by::

    :c:func:`VIDIOC_LOG_STATUS`

    Signed-off-by: Markus Heiser
    Signed-off-by: Jonathan Corbet

    Markus Heiser
     
  • e8f5c617f   doc-rst: add boilerplate to customize c-domain ... Browse Code »

    Add a sphinx-extension to customize the sphinx c-domain. No functional
    changes right yet, just the boilerplate code.

    Signed-off-by: Markus Heiser
    [ jc: coding-style tweak ]
    Signed-off-by: Jonathan Corbet

    Markus Heiser
     

19 Aug, 2016

1 commit

15 Aug, 2016

1 commit

  • 606b9ac81   doc-rst: generic way to build only sphinx sub-folders ... Browse Code »

    Add a generic way to build only a reST sub-folder with or
    without a individual *build-theme*.

    * control *sub-folders* by environment SPHINXDIRS
    * control *build-theme* by environment SPHINX_CONF

    Folders with a conf.py file, matching $(srctree)/Documentation/*/conf.py
    can be build and distributed *stand-alone*. E.g. to compile only the
    html of 'media' and 'gpu' folder use::

    make SPHINXDIRS="media gpu" htmldocs

    To use an additional sphinx-build configuration (*build-theme*) set the
    name of the configuration file to SPHINX_CONF. E.g. to compile only the
    html of 'media' with the *nit-picking* build use::

    make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs

    With this, the Documentation/conf.py is read first and updated with the
    configuration values from the Documentation/media/conf_nitpick.py.

    Signed-off-by: Markus Heiser
    Signed-off-by: Jonathan Corbet

    Markus Heiser
     

23 Jul, 2016

1 commit

  • 7e5b7d1b3   Merge branch 'docs-next' of git://git.lwn.net/linux into topic/docs-next ... Browse Code »

    * '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
     

21 Jul, 2016

1 commit

09 Jul, 2016

1 commit

  • fb6fc6c9a   doc-rst: parse-headers: remove trailing spaces ... Browse Code »

    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: Mauro Carvalho Chehab

    Mauro Carvalho Chehab
     

08 Jul, 2016

4 commits

  • 037763785   doc-rst: add kernel-include directive ... Browse Code »

    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: Markus Heiser
    Signed-off-by: Mauro Carvalho Chehab

    Markus Heiser
     
  • 153234c47   doc-rst: parse-headers: don't do substituition references ... Browse Code »

    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: Mauro Carvalho Chehab

    Mauro Carvalho Chehab
     
  • 526b88483   doc-rst: parse-headers: add an option to ignore enum symbols ... Browse Code »

    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: Mauro Carvalho Chehab

    Mauro Carvalho Chehab
     
  • 034e6c8e7   doc-rst: parse-headers: better handle comments at the source code ... Browse Code »

    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: Mauro Carvalho Chehab

    Mauro Carvalho Chehab
     

07 Jul, 2016

7 commits

01 Jul, 2016

1 commit

  • 0249a7644   doc-rst: flat-table directive - initial implementation ... Browse Code »

    Implements the reST flat-table directive.

    The ``flat-table`` is a double-stage list similar to the ``list-table`` with
    some additional features:

    * column-span: with the role ``cspan`` a cell can be extended through
    additional columns

    * row-span: with the role ``rspan`` a cell can be extended through
    additional rows

    * auto span rightmost cell of a table row over the missing cells on the right
    side of that table-row. With Option ``:fill-cells:`` this behavior can
    changed from *auto span* to *auto fill*, which automaticly inserts (empty)

    list tables

    The *list tables* formats are double stage lists. Compared to the
    ASCII-art they migth be less comfortable for readers of the
    text-files. Their advantage is, that they are easy to create/modify
    and that the diff of a modification is much more meaningfull, because
    it is limited to the modified content.

    The initial implementation was taken from the sphkerneldoc project [1]

    [1] https://github.com/return42/sphkerneldoc/commits/master/scripts/site-python/linuxdoc/rstFlatTable.py

    Signed-off-by: Markus Heiser
    [jc: fixed typos and misspellings in the docs]
    Signed-off-by: Jonathan Corbet

    Markus Heiser
     

10 Jun, 2016

2 commits

  • 03d35d9ec   Documentation/sphinx: add support for specifying extra export files ... Browse Code »

    Let the user specify file patterns where to look for the EXPORT_SYMBOLs
    in addition to the file with kernel-doc comments. This is directly based
    on the -export-file FILE option added to kernel-doc in "kernel-doc: add
    support for specifying extra files for EXPORT_SYMBOLs", but we extend
    that with globbing patterns in the Sphinx extension.

    The file patterns are added as options to the :export: and :internal:
    arguments of the kernel-doc directive. For example, to extract the
    documentation of exported functions from include/net/mac80211.h:

    .. kernel-doc:: include/net/mac80211.h
    :export: net/mac80211/*.c

    Without the file pattern, no exported functions would be found, as the
    EXPORT_SYMBOLs are placed in the various source files under
    net/mac80211.

    The matched files are also added as dependencies on the document in
    Sphinx, as they may affect the output. This is one of the reasons to do
    the globbing in the Sphinx extension instead of in scripts/kernel-doc.

    The file pattern remains optional, and is not needed if the kernel-doc
    comments and EXPORT_SYMBOLs are placed in the source file passed in as
    the main argument to the kernel-doc directive. This is the most common
    case across the kernel source tree.

    Signed-off-by: Jani Nikula

    Jani Nikula
     
  • 057de5c4d   Documentation/sphinx: use a more sensible string split in kernel-doc extension ... Browse Code »

    Using the default str.split doesn't return empty strings like the
    current version does.

    Signed-off-by: Jani Nikula

    Jani Nikula