1. 12 Jan, 2017 1 commit
  2. 21 Sep, 2016 1 commit
  3. 23 Aug, 2016 1 commit
  4. 22 Aug, 2016 5 commits
  5. 18 Aug, 2016 6 commits
  6. 14 Aug, 2016 1 commit
    • Markus Heiser's avatar
      doc-rst: generic way to build only sphinx sub-folders · 606b9ac8
      Markus Heiser authored
      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: default avatarMarkus Heiser <markus.heiser@darmarIT.de>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      606b9ac8
  7. 12 Aug, 2016 2 commits
  8. 20 Jul, 2016 1 commit
  9. 19 Jul, 2016 1 commit
    • Daniel Vetter's avatar
      doc/sphinx: Enable keep_warnings · 47d6d752
      Daniel Vetter authored
      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: default avatarDaniel Vetter <daniel.vetter@intel.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      47d6d752
  10. 15 Jul, 2016 1 commit
    • Mauro Carvalho Chehab's avatar
      doc-rst: Fix compilation of the pdf docbook · 520a2477
      Mauro Carvalho Chehab authored
      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: default avatarMauro 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.
      520a2477
  11. 08 Jul, 2016 1 commit
  12. 05 Jul, 2016 1 commit
  13. 30 Jun, 2016 1 commit
    • Markus Heiser's avatar
      doc-rst: flat-table directive - initial implementation · 0249a764
      Markus Heiser authored
      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.pySigned-off-by: default avatarMarkus Heiser <markus.heiser@darmarIT.de>
      [jc: fixed typos and misspellings in the docs]
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      0249a764
  14. 30 May, 2016 3 commits
    • Jani Nikula's avatar
      Documentation/sphinx: set version and release properly · c13ce448
      Jani Nikula authored
      Read the version and release from the top level Makefile (for use when
      Sphinx is invoked directly, by e.g. Read the Docs), but override them
      via Sphinx command line arguments in a normal documentation build.
      Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      c13ce448
    • Jani Nikula's avatar
      Documentation/sphinx: configure the kernel-doc extension · 24dcdeb2
      Jani Nikula authored
      Tell Sphinx where to find the extension, and pass on the kernel src tree
      and kernel-doc paths to the extension.
      
      With this, any .rst files under Documentation may contain the kernel-doc
      rst directive to include kernel-doc documentation from any source file.
      
      While building, it may be handy to pass kernel-doc extension
      configuration on the command line. For example, 'make SPHINXOPTS="-D
      kerneldoc_verbosity=0" htmldocs' silences all stderr output from
      kernel-doc when the kernel-doc exit code is 0. (The stderr will be
      logged unconditionally when the exit code is non-zero.)
      Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      24dcdeb2
    • Jani Nikula's avatar
      Documentation/sphinx: add basic working Sphinx configuration and build · 22cba31b
      Jani Nikula authored
      Add basic configuration and makefile to build documentation from any
      .rst files under Documentation using Sphinx. For starters, there's just
      the placeholder index.rst.
      
      At the top level Makefile, hook Sphinx documentation targets alongside
      (but independent of) the DocBook toolchain, having both be run on the
      various 'make *docs' targets.
      
      All Sphinx processing is placed into Documentation/Makefile.sphinx. Both
      that and the Documentation/DocBook/Makefile are now expected to handle
      all the documentation targets, explicitly ignoring them if they're not
      relevant for that particular toolchain. The changes to the existing
      DocBook Makefile are kept minimal.
      
      There is graceful handling of missing Sphinx and rst2pdf (which is
      needed for pdf output) by checking for the tool and python module,
      respectively, with informative messages to the user.
      
      If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but
      otherwise gracefully fall back to the Sphinx default theme, with an
      informative message to the user, and slightly less pretty HTML output.
      
      Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available),
      epubdocs and xmldocs targets. The output documents are written into per
      output type subdirectories under Documentation/output.
      
      Finally, you can pass options to sphinx-build using the SPHINXBUILD make
      variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose
      output from Sphinx.
      
      This is based on the original work by Jonathan Corbet, but he probably
      wouldn't recognize this as his own anymore.
      Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      22cba31b