summaryrefslogtreecommitdiff
path: root/Documentation/sphinx-static
AgeCommit message (Collapse)AuthorFilesLines
2023-12-20docs: translations: add translations links when they existVegard Nossum1-0/+53
Add a new Sphinx extension that knows about the translations of kernel documentation and can insert links to the translations at the top of the document. It basically works like this: 1. Register a new node type, LanguagesNode. 2. Register a new transform, TranslationsTransform, that inserts a new LanguageNode at the top of every document. The LanguageNode contains "pending references" to translations of the document. The key here is that these are pending (i.e. unresolved) references that may or may not actually exist. 3. Register a 'doctree-resolved' event that iterates over all the LanguageNode nodes. Any unresolved references are filtered out; the list of resolved references is passed to the 'translations.html' template and rendered as an HTML node (if HTML output is selected). Testing: make htmldocs, make latexdocs with Sphinx v4.3.2 and Firefox. v2: - changed bar into a drop-down menu - fixed language labels - fixed hysteresis reported by Akira Yokosawa Cc: Federico Vaga <federico.vaga@vaga.pv.it> Cc: Jani Nikula <jani.nikula@linux.intel.com> Cc: Akira Yokosawa <akiyks@gmail.com> Cc: Yanteng Si <siyanteng@loongson.cn> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231215123701.2712807-1-vegard.nossum@oracle.com
2023-12-15docs: Change <h4> style to use smaller font size than <h3>Donald Hunter1-0/+1
The docs currently have <h3> and <h4> set to the same font size which makes headings hard to distinguish. <h1> to <h3> already have entries in sphinx-static/custom.css to shrink their size a bit from the alabaster theme. Add <h4> to custom.css and set it to be smaller than <h3>. Signed-off-by: Donald Hunter <donald.hunter@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231212213137.98453-1-donald.hunter@gmail.com
2023-11-17Documentation: add tux logoVegard Nossum1-0/+6
We already have the logo, let's use it. Testing: make htmldocs Cc: Miguel Ojeda <ojeda@kernel.org> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231029074207.297663-1-vegard.nossum@oracle.com
2023-11-17docs: remove .toc-title classVegard Nossum1-5/+0
The "toc-title" class was introduced in commit ef88f10eb877 ("[media] doc-rst: backward compatibility with older Sphinx versions") as a workaround for Sphinx versions older than 1.4.x. However, these old versions have been deprecated since commit 31abfdda6527 ("docs: Deprecate use of Sphinx < 2.4.x"). Having now changed all the toc-title users to use the :caption: attribute, we can also remove the custom style. Note that the toc-title class is separate from the "kernel-toc" logic that was introduced in commit c404f5d4f099 ("docs: Add more information to the HTML sidebar"). Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231027081830.195056-12-vegard.nossum@oracle.com
2023-11-17docs: style toctree captions as headingsVegard Nossum1-0/+3
The rtd theme already styles toctree captions as headings, but the alabaster theme doesn't. Add this in. Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231027081830.195056-2-vegard.nossum@oracle.com
2023-02-08docs: Add more information to the HTML sidebarJonathan Corbet1-1/+47
Add a new sidebar template that creates a more RTD-like "fisheye" view of the current place in the document hierarchy. It is far from ideal, but some readers may find it better for navigating through the documentation as a whole. Add some CSS trickery as well to make the table of contents less intrusive when viewing the pages on a small screen. Reviewed-by: Akira Yokosawa <akiyks@gmail.com> Reviewed-by: David Gow <davidgow@google.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-11-02docs: Don't wire font sizes for HTML outputJonathan Corbet1-0/+1
The alabaster theme likes to provide explicit sizes for fonts, which overrides the users's own browser settings and is guaranteed to displease folks. Set the font size to "inherit" so that the users browser settings control the font size they get. We can use the font_size configuration option for the main body font (changing the size I'd already put there), but the sidebar size can only be set via custom CSS. Reported-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-10-19docs: improve the HTML formatting of kerneldoc commentsJonathan Corbet1-1/+15
Make a few changes to cause functions documented by kerneldoc to stand out better in the rendered documentation. Specifically, change kernel-doc to put the description section into a ".. container::" section, then add a bit of CSS to indent that section relative to the function prototype (or struct or enum definition). Tweak a few other CSS parameters while in the neighborhood to improve the formatting. Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-10-13docs: tweak some Alabaster style parametersJonathan Corbet1-0/+14
This is just the beginning: tighten up the layout a bit to improve the information density in the browser. Also reconfigure the page width in terms of character units (em) rather than pixels, making it more display-independent. To that end, add a custom.css file to tweak Alabaster CSS settings. Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-12-11docs: add support for RTD dark modeMauro Carvalho Chehab2-14/+39
This is actually an overlay on the top of the RTD theme, which requires to include first the RTD theme. It should be noticed that, when the dark theme is used, the DOCS_CSS files won't be the last CSS themes. So, it won't override the dark.css style by default. So, it is needed to force the them override with "!important". This small script, for instance, produces a nice output with the RTD dark theme: DOCS_THEME=sphinx_rtd_dark_mode cat << EOF > dark_override.css html body { font-family: arial,helvetica,sans-serif; } html[data-theme='dark'] body { color: white !important; } html[data-theme='dark'] .sig-name { color: green !important; } html[data-theme='dark'] .wy-menu-vertical a { color: #ffcc00 !important; } html[data-theme="dark"] h1, html[data-theme="dark"] h2, html[data-theme="dark"] h3 { color: #ffcc00 !important; } html[data-theme="dark"] h4, html[data-theme="dark"] h5, html[data-theme="dark"] h6 { color: #ffcc00 !important; } html[data-theme="dark"] h7, html[data-theme="dark"] h8, html[data-theme="dark"] h9 { color: #ffcc00 !important; } html[data-theme="dark"] .wy-nav-content a, html[data-theme="dark"] .wy-nav-content a:visited { color: #ffcc00 !important; } EOF make DOCS_CSS=dark_override.css DOCS_THEME=sphinx_rtd_dark_mode htmldocs Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/90d316e055ef7f4c9021b9eada8f8d3b2e750a66.1638870323.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-02doc-rst: Reduce CSS padding around FieldKees Cook1-0/+10
Right now any ":Field Name: Field Contents" lines end up with significant padding due to CSS from the "table" CSS which rightly needs padding to make tables readable. However, field lists don't need this as they tend to be stacked together. The future heavy use of fields in the parsed MAINTAINERS file needs this cleaned up, and existing users look better too. Note the needless white space (and misalignment of name/contents) between "Date" and "Author": https://www.kernel.org/doc/html/latest/accounting/psi.html This patch fixes this by lowering the padding with a more specific CSS. Signed-off-by: Kees Cook <keescook@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-10-07docs: improve readability for people with poorer eyesightDarrick J. Wong1-0/+38
My eyesight is not in good shape, which means that I have difficulty reading the online Linux documentation. Specifically, body text is oddly small compared to list items and the contrast of various text elements is too low for me to be able to see easily. Therefore, alter the HTML theme overrides to make the text larger and increase the contrast for better visibility, and trust the typeface choices of the reader's browser. For the PDF output, increase the text size, use a sans-serif typeface for sans-serif text, and use a serif typeface for "roman" serif text. Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com> Acked-by: Dave Chinner <dchinner@redhat.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17docs RTD theme: code-block with line nos - lines and line numbers don't line up.Markus Heiser1-0/+11
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-17docs RDT theme: fix bottom margin of lists itemsMarkus Heiser1-0/+6
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>
2016-10-04Merge tag 'docs-4.9' of git://git.lwn.net/linuxLinus Torvalds1-1/+14
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-09-21doc-rst: add CSS styles for :kbd: and :menuselection:Mauro Carvalho Chehab1-1/+14
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-08-14doc-rst: customize RTD theme, drop padding of inline literalMarkus Heiser1-1/+2
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-07-19[media] doc-rst: backward compatibility with older Sphinx versionsMauro Carvalho Chehab1-0/+5
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-05doc-rst: customize RTD theme, captions & inline literalMarkus Heiser1-0/+25
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-05doc-rst: customize RTD theme, table & full widthMarkus Heiser1-1/+20
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-05doc-rst: boilerplate HTML theme customizationMarkus Heiser1-0/+9
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>