Eric Lee / smarc-fsl-linux-kernel

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

3 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
     
  • 06173fe33   Documentation/sphinx: remove unnecessary temporary variable ... Browse Code »

    Leftover cruft. No functional changes.

    Signed-off-by: Jani Nikula

    Jani Nikula
     

04 Jun, 2016

1 commit

  • d90368f2f   doc/sphinx: Track line-number of starting blocks ... Browse Code »

    Design is pretty simple: kernel-doc inserts breadcrumbs with line
    numbers, and sphinx picks them up. At first I went with a sphinx
    comment, but inserting those at random places seriously upsets the
    parser, and must be filtered. Hence why this version now uses "#define
    LINEO " since one of these ever escape into output it's pretty clear
    there is a bug.

    It seems to work well, and at least the 2-3 errors where sphinx
    complained about something that was not correct in kernel-doc text the
    line numbers matched up perfectly.

    v2: Instead of noodling around in the parser state machine, create
    a ViewList and parse it ourselves. This seems to be the recommended
    way, per Jani's suggestion.

    v3:
    - Split out ViewList pach. Splitting the kernel-doc changes from the
    sphinx ones isn't possible, since emitting the LINENO lines wreaks
    havoc with the rst formatting. We must filter them.

    - Improve the regex per Jani's suggestions, and compile it just once
    for speed.

    - Now that LINENO lines are eaten, also add them to function parameter
    descriptions. Much less content and offset than for in-line struct
    member descriptions, but still nice to know which exact continuation
    line upsets sphinx.

    - Simplify/clarify the line +/-1 business a bit.

    v4: Split out the scripts/kernel-doc changes and make line-numbers
    opt-in, as suggested by Jani.

    Cc: Jani Nikula
    Cc: linux-doc@vger.kernel.org
    Cc: Jonathan Corbet
    Signed-off-by: Daniel Vetter
    Signed-off-by: Jani Nikula

    Daniel Vetter
     

03 Jun, 2016

1 commit

  • 16e161c8c   doc/sphinx: Stop touching state_machine internals ... Browse Code »

    Instead of just forcefully inserting our kernel-doc input and letting
    the state machine stumble over it the recommended way is to create
    ViewList, parse that and then return the list of parsed nodes.

    Suggested by Jani.

    Cc: Jani Nikula
    Cc: linux-doc@vger.kernel.org
    Cc: Jonathan Corbet
    Signed-off-by: Daniel Vetter
    Signed-off-by: Jani Nikula

    Daniel Vetter
     

01 Jun, 2016

2 commits

  • 9cc1a44c0   doc/sphinx: Pass right filename as source ... Browse Code »

    With this error output becomes almost readable. The line numbers are
    still totally bonghits, but that's a lot harder to pull out of
    kerneldoc. We'd essentially have to insert some special markers in the
    kernel-doc output, split the output along these markers and then
    insert each block separately using

    state_machine.insert_input(block, source, first_line)

    Cc: Jani Nikula
    Cc: linux-doc@vger.kernel.org
    Cc: Jonathan Corbet
    Signed-off-by: Daniel Vetter
    Signed-off-by: Jani Nikula

    Daniel Vetter
     
  • ba3501859   Documentation/sphinx: fix kernel-doc extension on python3 ... Browse Code »

    Reconcile differences between python2 and python3 on dealing with
    stdout, stderr from Popen. This fixes "name 'unicode' is not defined"
    errors on python3. We'll need to try to keep the extension working on
    both python-sphinx and python3-sphinx so we don't need two copies.

    Reported-and-tested-by: Marius Vlad
    Signed-off-by: Jani Nikula

    Jani Nikula
     

30 May, 2016

4 commits