Commit graph

9 commits

Author SHA1 Message Date
Markus Heiser
4c0477899f docs RTD theme: code-block with line nos - lines and line numbers don't line up.
In a code-block with line numbers (option :lineno:) there is a
misalignment of the rendered source code lines on the right side and the
line numbers on the left side.

  https://github.com/rtfd/sphinx_rtd_theme/issues/419

Since this issue is reported to the RTD theme project, it might be fixed
in the future (take this as a interim solution).

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17 13:48:45 -06:00
Markus Heiser
916f677ada docs RDT theme: fix bottom margin of lists items
List items with two ore more blocks are not well rendered. E.g. the gap
between last block (l1-b2) of the first list item and the following list
item (L2) is to small::

    * L1 xxxxxxxxxx
      xxxxxxxxxxxxx

      l1-b2 xxxxxxx
      xxxxxxxxxxxxx
    * L2 xxxxxxxxxx
      xxxxxxxxxxxxx

So that it can be read more liquidly, a distance was added to the last
block (l1-b2)::

    * L1 xxxxxxxxxx
      xxxxxxxxxxxxx

      l1-b2 xxxxxxx
      xxxxxxxxxxxxx

    * L2 xxxxxxxxxx
      xxxxxxxxxxxxx

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17 13:47:46 -06:00
Linus Torvalds
02bafd96f3 This is the documentation update pull for the 4.9 merge window.
The Sphinx transition is still creating a fair amount of work.  Here we
 have a number of fixes and, importantly, a proper PDF output solution,
 thanks to Jani Nikula, Mauro Carvalho Chehab and Markus Heiser.
 
 I've started a couple of new books: a driver API book (based on the old
 device-drivers.tmpl) and a development tools book.  Both are meant to show
 how we can integrate together our existing documentation into a more
 coherent and accessible whole.  It involves moving some stuff around and
 formatting changes, but, I think, the results are worth it.  The good news
 is that most of our existing Documentation/*.txt files are *almost* in RST
 format already; the amount of messing around required is minimal.
 
 And, of course, there's the usual set of updates, typo fixes, and more.
 -----BEGIN PGP SIGNATURE-----
 
 iQIcBAABAgAGBQJX8st8AAoJEI3ONVYwIuV6d10P/0Zsnx3hSSx22aHxP4kVb4s/
 NTttFAienYzc2fYYD3K/wMQbSbprW8Pp7uSP1suzAbU5FGgfLyDFQHnE0AVqFNiT
 MHVc5oBWp4ZlvNcyQUeXOsKtb5Rin00XHjer2mm/T9HfgmCYR4i+C9HQuv+J94Jf
 sgeI4IimvLjlp7dDbhcIfdqCpZ+UwBSpSm9w5f7astYDjocJHrkBqyk/46Ir4qz9
 +2joNZRWMUatrQYJWMJnnvlnx8lHhkDjaL/Egy+f7ucpddEkbGvWvabGCSMtCyzS
 CKlA53Y4wS59cNFkAuxsHjun4TcQhbZn/iBIM+8aOdameO0ksC4jSoND2P6N6vKF
 dHkAkayP9ChW3k/J8D+3cGIJNFiaYevEXcgxLyShjCuh4t4yfOC9aIGUl3Ye9/mR
 tiKpMsvzmwJ+yO+kzJsxWTmRAX5wdI1Z062ltiS1dmSbl3c3NgQFpfP7V7AJSQ7c
 DzkuoUnGEqJOHm64dAZQuxL4jj6StzejjxlhH0bIjbNn1a9VlX9afwsdJaXA+kmr
 jQHJtR0wD1mLMYYdvNEiqvcCbumG+kaXmH6eUQadRxruRdZyhi1Z6Ql1CtwQGtbR
 SetC/MVxIN3fGPbZYhJ162xVjQ8OeX0ndRmRjy6SBDMoRGSKqi2IME8JAGOshxE0
 0uYAJJFZOeiR6KaPnci/
 =kGKl
 -----END PGP SIGNATURE-----

Merge tag 'docs-4.9' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "This is the documentation update pull for the 4.9 merge window.

  The Sphinx transition is still creating a fair amount of work. Here we
  have a number of fixes and, importantly, a proper PDF output solution,
  thanks to Jani Nikula, Mauro Carvalho Chehab and Markus Heiser.

  I've started a couple of new books: a driver API book (based on the
  old device-drivers.tmpl) and a development tools book. Both are meant
  to show how we can integrate together our existing documentation into
  a more coherent and accessible whole. It involves moving some stuff
  around and formatting changes, but, I think, the results are worth it.
  The good news is that most of our existing Documentation/*.txt files
  are *almost* in RST format already; the amount of messing around
  required is minimal.

  And, of course, there's the usual set of updates, typo fixes, and
  more"

* tag 'docs-4.9' of git://git.lwn.net/linux: (120 commits)
  URL changed for Linux Foundation TAB
  dax : Fix documentation with respect to struct pages
  iio: Documentation: Correct the path used to create triggers.
  docs: Remove space-before-label guidance from CodingStyle
  docs-rst: add inter-document cross references
  Documentation/email-clients.txt: convert it to ReST markup
  Documentation/kernel-docs.txt: reorder based on timestamp
  Documentation/kernel-docs.txt: Add dates for online docs
  Documentation/kernel-docs.txt: get rid of broken docs
  Documentation/kernel-docs.txt: move in-kernel docs
  Documentation/kernel-docs.txt: remove more legacy references
  Documentation/kernel-docs.txt: add two published books
  Documentation/kernel-docs.txt: sort books per publication date
  Documentation/kernel-docs.txt: adjust LDD references
  Documentation/kernel-docs.txt: some improvements on the ReST output
  Documentation/kernel-docs.txt: Consistent indenting: 4 spaces
  Documentation/kernel-docs.txt: Add 4 paper/book references
  Documentation/kernel-docs.txt: Improve layouting of book list
  Documentation/kernel-docs.txt: Remove offline or outdated entries
  docs: Clean up bare :: lines
  ...
2016-10-04 13:54:07 -07:00
Mauro Carvalho Chehab
1414f04888 doc-rst: add CSS styles for :kbd: and :menuselection:
As we're about to use those two markups, add them to the
theme style overrride.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:24:35 -06:00
Markus Heiser
d1669c8288 doc-rst: customize RTD theme, drop padding of inline literal
Remove the distracting (left/right) padding of inline literals. (HTML
<code>). Requested and discussed in [1].

[1] http://www.spinics.net/lists/linux-media/msg103991.html

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-14 12:15:09 -06:00
Mauro Carvalho Chehab
ef88f10eb8 [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>
2016-07-19 12:35:08 -03:00
Markus Heiser
4eb40f14dc doc-rst: customize RTD theme, captions & inline literal
The layout of (table) captions in the RTD theme is a bit ugly and the
bordered, red colored of inline literals is a bit to gaudy. The
requirements has been discussed in the ML [1].

captions:

  - captions should have 100% (not 85%) font size
  - hide the permalink symbol as long as link is not hovered

inline literal:

  - drop the borderbox and red color

[1] http://article.gmane.org/gmane.linux.drivers.video-input-infrastructure/101099

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
2016-07-05 14:39:51 -03:00
Markus Heiser
9abaf979ab doc-rst: customize RTD theme, table & full width
The default table layout of the RTD theme does not fit for vast tables,
like the ones we have in the linux_tv project. This has been discussed
on the ML [1].

The RTD theme is a two column layout, with a navigation column on the
left and a content column on the right:

content column

 RTD theme's default is 800px as max width for the content, but we have
 tables with tons of columns, which need the full width of the
 view-port (BTW: *full width* is what DocBook's HTML is).

table

   - sequences of whitespace should collapse into a single whitespace.
   - make the overflow auto (scrollbar if needed)
   - align caption "left" ("center" is unsuitable on vast tables)

[1] http://article.gmane.org/gmane.linux.kernel/2216509

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
2016-07-05 14:39:51 -03:00
Markus Heiser
bc21467114 doc-rst: boilerplate HTML theme customization
Implements the minimal boilerplate for Sphinx HTML theme customization.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-05 14:38:49 -03:00