- Dec 10, 2021
-
-
Mauro Carvalho Chehab authored
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>
-
Mauro Carvalho Chehab authored
When RTD is not installed or when THEME=classic is used, the produced docs contain some weird selections. As this theme has several variables to customize it, set them, in order to produce a nicer output. Signed-off-by:
-
Mauro Carvalho Chehab authored
Specially when the RTD theme is not used, it makes sense to allow specifying extra CSS files via a make variable. Signed-off-by:
-
Mauro Carvalho Chehab authored
Instead of having RTD as an almost mandatory theme, allow the user to select other themes via DOCS_THEME environment var. There's a catch, though: as the current theme override logic is dependent of the RTD theme, we need to move the code which adds the CSS overrides to be inside the RTD theme logic. Signed-off-by:
-
- Nov 29, 2021
-
-
Mauro Carvalho Chehab authored
As described at: https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs since Sphinx 1.8, the standard way to setup a custom theme is to use html_css_files. While using html_context is OK with RTD 0.5.2, it doesn't work with 1.0.0, causing the theme to not load, producing a very weird html. Tested with: - Sphinx 1.7.9 + sphinx-rtd-theme 0.5.2 - Sphinx 2.4.4 + sphinx-rtd-theme 0.5.2 - Sphinx 2.4.4 + sphinx-rtd-theme 1.0.0 - Sphinx 4.3.0 + sphinx-rtd-theme 1.0.0 Reported-by:
Hans Verkuil <hverkuil@xs4all.nl> Tested-by:
Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by:
Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/80009f0d17ea0840d81e7e16fff6e7677919fdfc.1638004294.git.mchehab+huawei@kernel.org Signed-off-by:
-
- Oct 12, 2021
-
-
Akira Yokosawa authored
Fancyhdr prior to v4.0 outputs a message per document as follows: Package Fancyhdr Warning: \headheight is too small (12.0pt): Make it at least 13.59999pt. We now make it that large for the rest of the document. This may cause the page layout to be inconsistent, however. Fancyhdr v4.0 complains (once a page!) as follows: Package fancyhdr Warning: \headheight is too small (12.0pt): (fancyhdr) Make it at least 13.59999pt, for example: (fancyhdr) \setlength{\headheight}{13.59999pt}. (fancyhdr) You might also make \topmargin smaller to compensate: (fancyhdr) \addtolength{\topmargin}{-1.59999pt}. Related item in fancyhdr v4.0 announcement on 2021-01-04 [1]: Backward incompatible changes: - Eliminate adjustments of \headheight or \footskip, when the header or footer is too high. [1]: https://www.ctan.org/ctan-ann/id/mailman.2685.1609863692.2532.ctan-ann@ctan.org Silence the warnings by adding a couple of \addtolength commands in the preamble. Signed-off-by:
-
- Sep 06, 2021
-
-
Akira Yokosawa authored
There were typos in the fallback definitions of dummy LaTeX macros for systems without CJK fonts. They cause build errors in "make pdfdocs" on such systems. Fix them. Fixes: e291ff6f ("docs: pdfdocs: Add CJK-language-specific font settings") Signed-off-by:
-
- Aug 12, 2021
-
-
Akira Yokosawa authored
Quotation marks in "KR" and "JP" variants of Noto CJK fonts are half width. xeCJK assumes they are full width by default and does excessive kerning around them in Korean and Japanese translations. Give xeCJK proper hints by the \xeCJKDeclareCharClass command. Signed-off-by:
-
Akira Yokosawa authored
Noto CJK fonts don't provide italic shapes. The AutoFakeSlant option of fontspec and xeCJK packages can be used as a workaround. Signed-off-by:
-
Akira Yokosawa authored
CJK documents are much easier to read with a wider baseline stretch. Applying onehalfspacing option of "setspace" package looks reasonable. Note: \usepackage{setspace} needs to be before that of hyperref in the preamble. The 'extrapackages' key (available since Sphinx 2.3) is for this purpose. For systems with Sphinx < 2.3, dummy commands of \onehalfspacing and \singlespacing are provided instead. One-half spacing is not effective in LaTeX sources generated by such revisions of Sphinx. Signed-off-by: -
Akira Yokosawa authored
In Korean typesetting, inter-phrase spaces in Hangul text have a similar role as the the inter-word spaces in Latin text. They can be preserved by the \xeCJKsetup{CJKspace=true} option. Signed-off-by: -
Akira Yokosawa authored
"Noto Serif CJK SC" and its variants suit better with the roman font of Latin letters. On some distros such as Fedora, it is possible to partially install "Noto Sans CJK" fonts. So, if the Serif fonts are not found on the system, fall back to the Sans fonts. Signed-off-by:
-
Akira Yokosawa authored
zh_TW, ko_KR, and ja_JP translations have their preferred glyph sets different from that of zh_CN. To switch CJK font in the middle of the translations, introduce custom LaTeX macros listed below: \kerneldocBeginSC \kerneldocEndSC \kerneldocBeginTC \kerneldocEndTC \kerneldocBeginKR \kerneldocEndKR \kerneldocBeginJP \kerneldocEndJP , and embed a pair of macros in each language's index.rst. NOTE 1: Update of zh_TW/index.rst is deferred to a follow-up change. NOTE 2: Custom macros added here do not imply \kerneldocCJK(on|off). This is intentional. For example, \kerneldocCJKoff needs to be at the top of Italian translations' index.rst for the footer of final zh_TW page to be properly typeset. Signed-off-by: -
Akira Yokosawa authored
To make generated LaTeX code portable across systems with different sets of available fonts, convert font-availability check in python code to LaTeX code by using a conditional command provided by the "fontspec" package. This will help those who run Sphinx on one machine/container and run latexmk on other machines/containers. Remove import of check_output as it is unused any more. Signed-off-by:
-
- Jun 17, 2021
-
-
Jonathan Corbet authored
Sphinx 3.0 works at this point (albeit slowly) so stop scaring people with a loud warning. We also don't need to babble about CJK support in the LaTeX build. Signed-off-by:
-
- Jun 01, 2021
-
-
Akira Yokosawa authored
Setting a reasonable width to \tymin prevents column squeezing by tabulary. Width of 20em works well in almost all the tables still in the ascii-art format. Excerpt from tabulary package documentation at [1]: To stop very narrow columns being too 'squeezed' by this process any columns that are narrower than \tymin are set to their natural width. [1]: https://mirrors.ctan.org/macros/latex/contrib/tabulary/tabulary.pdf Note: Sphinx has its own default value of \tymin set in sphinxlatextables.sty (Sphinx 4.0.2) and sphinxmulticell.sty (Sphinx 2.4.4) as follows: \setlength{\tymin}{3\fontcharwd\font`0 } , which is not sufficient for kernel-doc. Tested against Sphinx versions 2.4.4 and 4.0.2. Signed-off-by:
-
- May 27, 2021
-
-
Akira Yokosawa authored
Activating xeCJK in English and Italian-translation documents results in sub-optimal typesetting with wide-looking apostrophes and quotation marks. The xeCJK package provides macros for enabling and disabling its effect in the middle of a document, namely \makexeCJKactive and \makexeCJKinactive. So the goal of this change is to activate xeCJK in the relevant chapters in translations. To do this: o Define custom macros in the preamble depending on the availability of the "Noto Sans CJK" font so that those macros can be used regardless of the use of xeCJK package. o Patch \sphinxtableofcontents so that xeCJK is inactivated after table of contents. o Embed those custom macros in each language's index.rst file as a ".. raw:: latex" construct. Note: A CJK chapter needs \kerneldocCJKon in front of its chapter heading, while a non-CJK chapter should have \kerneldocCJKoff below its chapter heading. This is to make sure the CJK font is available to CJK chapter's heading and ending page's footer. Tested against Sphinx versions 2.4.4 and 4.0.2. Signed-off-by:Wu XiangCheng <bobwxc@email.cn> Reviewed-by:
-
- Mar 08, 2021
-
-
Mauro Carvalho Chehab authored
Changeset f546ff0c ("Move our minimum Sphinx version to 1.7") cleaned up some compatibility issues with previous Sphinx versions, but it also dropped the PDF margin sets. Without that, the media documentation won't build fine, as the margins are too wide to display texts with monospaced fonts. While here, align the "latex_elements = {" values, and add a few other sphinxsetup configs in order to allow Sphinx to wrap long lines on literal blocks. Fixes: f546ff0c ("Move our minimum Sphinx version to 1.7") Signed-off-by:
-
- Feb 22, 2021
-
-
Matthew Wilcox authored
The current documentation build looks like this: $ make htmldocs SPHINX htmldocs --> file:///home/willy/kernel/linux-next/Documentation/output make[2]: Nothing to be done for 'html'. WARNING: The kernel documentation build process support for Sphinx v3.0 and above is brand new. Be prepared for possible issues in the generated output. $ That extra indentation before my next prompt isn't pretty. This patch fixes it, but I'm not a pythonista, and maybe there's a better way. Signed-off-by:
Matthew Wilcox (Oracle) <willy@infradead.org> Link: https://lore.kernel.org/r/20210215161757.GD2858050@casper.infradead.org [jc: tweaked for the "better way"] Signed-off-by:
-
- Feb 01, 2021
-
-
Jonathan Corbet authored
As promised, drop support for some ancient sphinx releases, along with a lot of the cruft that was required to make that support work. Signed-off-by:
-
- Dec 11, 2020
-
-
Jonathan Corbet authored
The time has come to drop support for some truly ancient versions of sphinx; put in a warning now. Signed-off-by:
-
- Dec 03, 2020
-
-
Mauro Carvalho Chehab authored
Add a feature list matrix at the admin-guide. Signed-off-by:
-
- Oct 30, 2020
-
-
Mauro Carvalho Chehab authored
As we don't want a generic Sphinx extension to execute commands, change the one proposed to Markus to call the abi_book.pl script. Use a script to parse the Documentation/ABI directory and output it at the admin-guide. Acked-by:
Greg Kroah-Hartman <gregkh@linuxfoundation.org>
-
- Oct 28, 2020
-
-
Mauro Carvalho Chehab authored
One of the checks for Sphinx 3+ is broken, causing some C warnings to return back with Sphinx 4.0.x. Signed-off-by:
-
- Oct 15, 2020
-
-
Mauro Carvalho Chehab authored
After the build fix patches, it is believed that the output with Sphinx 3.x won't be a problem. Still, the C domain support was re-written, and this can have caused hidden issues. So, let's keep the warning, changing it to a lighter warning text. Signed-off-by: -
Mauro Carvalho Chehab authored
Sphinx C parser for the C domain is now more pedantic when trying to identify the function types. That prevents scope macros to be used as type defines. Yet, since 3.0.2, it is possible to provide it a list of such macros. Add them, in order to solve several Sphinx 3.x warnings. Signed-off-by:
-
- Sep 04, 2020
-
-
Jonathan Corbet authored
The Sphinx 3.x upgrade broke a number of things in our special "cdomain" module that are not easy to fix. For now, just disable that module for the 3.x build and put out a warning that the build will not be perfect. Signed-off-by:
-
- Jun 08, 2020
-
-
Alexander A. Klimov authored
Rationale: Reduces attack surface on kernel devs opening the links for MITM as HTTPS traffic is much harder to manipulate. Deterministic algorithm: For each file: For each line: If doesn't contain `\bxmlns\b`: For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`: If both the HTTP and HTTPS versions return 200 OK and serve the same content: Replace HTTP with HTTPS. Signed-off-by:Alexander A. Klimov <grandmaster@al2klimov.de> Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de Signed-off-by:
-
- Apr 20, 2020
-
-
Mauro Carvalho Chehab authored
The building system can auto-generate a list of documents since commit: 9d42afbe ("docs: pdf: add all Documentation/*/index.rst to PDF output"). The added logic there allows keeping the existing list, but there's not real reason to keep it. Now, the media document has gone (it was split into tree). So, it sounds about time to get rid of the manual entries, and let the script to generate it automatically instead. Signed-off-by:
-
- Mar 20, 2020
-
-
Mauro Carvalho Chehab authored
The autosectionlabel extension is nice, as it allows to refer to a section by its name without requiring any extra tag to create a reference name. However, on its default, it has two serious problems: 1) the namespace is global. So, two files with different "introduction" section would create a label with the same name. This is easily solvable by forcing the extension to prepend the file name with: autosectionlabel_prefix_document = True 2) It doesn't work hierarchically. So, if there are two level 1 sessions (let's say, one labeled "open" and another one "ioctl") and both have a level 2 "synopsis" label, both section 2 will have the same identical name. Currently, there's no way to tell Sphinx to create an hierarchical reference like: open / synopsis ioctl / synopsis This causes around 800 warnings. So, the fix should be to not let autosectionlabel to produce references for anything that it is not at a chapter level within any doc, with: autosectionlabel_maxdepth = 2 Fixes: 58ad30cf ("docs: fix reference to core-api/namespaces.rst") Signed-off-by:
-
- Mar 19, 2020
-
-
Jonathan Corbet authored
Fix a couple of dangling links to core-api/namespaces.rst by turning them into proper references. Enable the autosection extension (available since Sphinx 1.4) to make this work. Co-developed-by:
Federico Vaga <federico.vaga@vaga.pv.it> Fixes: fcfacb9f ("doc: move namespaces.rst from kbuild/ to core-api/") Signed-off-by:
-
- Oct 02, 2019
-
-
Kees Cook authored
In order to have the MAINTAINERS file visible in the rendered ReST output, this makes some small changes to the existing MAINTAINERS file to allow for better machine processing, and adds a new Sphinx directive "maintainers-include" to perform the rendering. Features include: - Per-subsystem reference links: subsystem maintainer entries can be trivially linked to both internally and external. For example: https://www.kernel.org/doc/html/latest/process/maintainers.html#secure-computing - Internally referenced .rst files are linked so they can be followed when browsing the resulting rendering. This allows, for example, the future addition of maintainer profiles to be automatically linked. - Field name expansion: instead of the short fields (e.g. "M", "F", "K"), use the indicated inline "full names" for the fields (which are marked with "*"s in MAINTAINERS) so that a rendered subsystem entry is more human readable. Email lists are additio...
-
- Jul 17, 2019
-
-
Mauro Carvalho Chehab authored
If we try to build a book with asian characters with XeLaTeX and the font is not available, it will produce an error. So, instead, add a logic at conf.py to detect if the proper font is installed. This will avoid an error while building the document, although the result may not be readable. Signed-off-by:Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
-
Mauro Carvalho Chehab authored
In order to be able to output Asian symbols with XeLaTeX, we need the xeCJK package, and a default font for CJK symbols. Signed-off-by: -
Mauro Carvalho Chehab authored
Currently, all index files should be manually added to the latex_documents array at conf.py. While this allows fine-tuning some LaTeX specific things, like the name of the output file and the name of the document, it is not uncommon to forget adding new documents there. So, add a logic that will seek for all Documentation/*/index.rst. If the index is not yet at latex_documents, it includes using a reasonable default. Signed-off-by:
-
- Jun 30, 2019
-
-
Stephen Kitt authored
The handling of dashes in particular results in confusing documentation in a number of instances, since "--" becomes an en-dash. This disables SmartyPants wholesale, losing smart quotes along with smart dashes. With Sphinx 1.6 we could fine-tune the conversion, using the new smartquotes and smartquotes_action settings. Signed-off-by:
Stephen Kitt <steve@sk2.org> Signed-off-by:
-
- Jun 26, 2019
-
-
Jonathan Corbet authored
Rather than fill our text files with :c:func:`function()` syntax, just do the markup via a hook into the sphinx build process. Signed-off-by:
-
- May 24, 2019
-
-
Jonathan Corbet authored
Our version check in Documentation/conf.py never envisioned a world where Sphinx moved beyond 1.x. Now that the unthinkable has happened, fix our version check to handle higher version numbers correctly. Cc: stable@vger.kernel.org Signed-off-by:
-
- Oct 07, 2018
-
-
Darrick J. Wong authored
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:
-
- Oct 05, 2018
-
-
Darrick J. Wong authored
Move the ext4 data structures book to Documentation/filesystems/ext4/ since the administrative information moved elsewhere. Signed-off-by:
Theodore Ts'o <tytso@mit.edu>
-
