summaryrefslogtreecommitdiffstats
path: root/Documentation/conf.py
Commit message (Collapse)AuthorAgeFilesLines
* Merge tag 'docs-6.1' of git://git.lwn.net/linuxLinus Torvalds2022-10-031-2/+40
|\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Pull documentation updates from Jonathan Corbet: "There's not a huge amount of activity in the docs tree this time around, but a few significant changes even so: - A complete rewriting of the top-level index.rst file, which mostly reflects itself in a redone top page in the HTML-rendered docs. The hope is that the new organization will be a friendlier starting point for both users and developers. - Some math-rendering improvements. - A coding-style.rst update on the use of BUG() and WARN() - A big maintainer-PHP guide update. - Some code-of-conduct updates - More Chinese translation work Plus the usual pile of typo fixes, corrections, and updates" * tag 'docs-6.1' of git://git.lwn.net/linux: (66 commits) checkpatch: warn on usage of VM_BUG_ON() and other BUG variants coding-style.rst: document BUG() and WARN() rules ("do not crash the kernel") Documentation: devres: add missing IO helper Documentation: devres: update IRQ helper Documentation/mm: modify page_referenced to folio_referenced Documentation/CoC: Reflect current CoC interpretation and practices docs/doc-guide: Add documentation on SPHINX_IMGMATH docs: process/5.Posting.rst: clarify use of Reported-by: tag docs, kprobes: Fix the wrong location of Kprobes docs: add a man-pages link to the front page docs: put atomic*.txt and memory-barriers.txt into the core-api book docs: move asm-annotations.rst into core-api docs: remove some index.rst cruft docs: reconfigure the HTML left column docs: Rewrite the front page docs: promote the title of process/index.rst Documentation: devres: add missing SPI helper Documentation: devres: add missing PINCTRL helpers docs: hugetlbpage.rst: fix a typo of hugepage size docs/zh_CN: Add new translation of admin-guide/bootconfig.rst ...
| * docs: reconfigure the HTML left columnJonathan Corbet2022-09-291-1/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Use the html_sidebars directive to get a more useful set of links in the left column. Unfortunately, this is a no-op with the default RTD theme, but others observe it. Reviewed-by: David Vernet <void@manifault.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Acked-by: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/20220927160559.97154-4-corbet@lwn.net Signed-off-by: Jonathan Corbet <corbet@lwn.net>
| * docs/conf.py: Respect env variable SPHINX_IMGMATHAkira Yokosawa2022-09-271-2/+14
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | On some distros with coarse-grained packaging policy, dvipng is installed along with latex. In such cases, math rendering will use imgmath by default. It is possible to override the choice by specifying the option string of "-D html_math_renderer='mathjax'" to sphinx-build (Sphinx >= 1.8). To provide developers an easier-to-use knob, add code for an env variable "SPHINX_IMGMATH" which overrides the automatic choice of math renderer for html docs. SPHINX_IMGMATH=yes : Load imgmath even if dvipng is not found SPHINX_IMGMATH=no : Don't load imgmath (fall back to mathjax) Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/5a582b2b-d51c-a062-36b2-19479cf68fab@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
| * docs/conf.py: Treat mathjax as fallback math rendererAkira Yokosawa2022-09-271-1/+26
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Currently, math expressions using the "math::" directive or the ":math:" role of Sphinx need the imgmath extension for proper rendering in html and epub builds. imgmath requires dvipng (and latex). Otherwise, "make htmldocs" will complain of missing commands. As a matter of fact, the mathjax extension is loaded by default since Sphinx v1.8 and it is good enough for html docs without any dependency on texlive packages. Stop loading the imgmath extension for html docs unless requirements for imgmath are met. To find out whether required commands are available, add a helper find_command(), which is a wrapper of shutil.which(). For epub docs, keep the same behavior of always loading imgmath. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/a6a877fc-dc93-2bda-a6d3-37001d99942a@gmail.com [jc: Took out the writing of the math_renderer decision] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* | docs/conf.py: add function attribute '__fix_address' to conf.pyMenglong Dong2022-08-261-0/+1
|/ | | | | | | | | | | | | | | | | | Stephen Rothwell reported htmldocs warning when merging net-next: Documentation/networking/kapi:26: net/core/skbuff.c:780: WARNING: Error in declarator or parameters Invalid C declaration: Expecting "(" in parameters. [error at 19] void __fix_address kfree_skb_reason (struct sk_buff *skb, enum skb_drop_reason reason) -------------------^ Add __fix_address keyword to c_id_attributes array in conf.py to fix the warning. Link: https://lore.kernel.org/linux-next/20220825154105.534d78ab@canb.auug.org.au/ Reported-by: Stephen Rothwell <sfr@canb.auug.org.au> Signed-off-by: Menglong Dong <imagedong@tencent.com> Tested-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs/conf.py: Cope with removal of language=None in Sphinx 5.0.0Akira Yokosawa2022-06-011-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | One of the changes in Sphinx 5.0.0 [1] says [sic]: 5.0.0 final - #10474: language does not accept None as it value. The default value of language becomes to 'en' now. [1]: https://www.sphinx-doc.org/en/master/changes.html#release-5-0-0-released-may-30-2022 It results in a new warning from Sphinx 5.0.0 [sic]: WARNING: Invalid configuration value found: 'language = None'. Update your configuration to a valid langauge code. Falling back to 'en' (English). Silence the warning by using 'en'. It works with all the Sphinx versions required for building kernel documentation (1.7.9 or later). Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/bd0c2ddc-2401-03cb-4526-79ca664e1cbe@gmail.com Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Pull LaTeX preamble part out of conf.pyAkira Yokosawa2022-02-241-171/+13
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Quote from Jon's remark [1]: I do notice that Documentation/conf.py is getting large and unapproachable. At some future point, it might be nice to pull all of the latex stuff out into a separate file where it won't scare people who stumble into it by accident. Pull LaTeX preamble settings added since commit 3b4c963243b1 ("docs: conf.py: adjust the LaTeX document output") out into sphinx/kerneldoc-preamble.sty. It will be copied to the build directory by the added "latex_additional_files" setting in conf.py. As a bonus, LaTeX/TeX code can be maintained without escaping backslashes. To compensate the loss of change history in sphinx/kerneldoc-preamble.sty, here is a list of changes made in conf.py: - f7ebe6b76940 ("docs: Activate exCJK only in CJK chapters") - 0afd4df0d16a ("docs: pdfdocs: Prevent column squeezing by tabulary") - 659653c9e546 ("docs: pdfdocs: Refactor config for CJK document") - e291ff6f5a03 ("docs: pdfdocs: Add CJK-language-specific font settings") - 7eb368cc319b ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible") - 35382965bdd2 ("docs: pdfdocs: Preserve inter-phrase space in Korean translations") - 77abc2c230b1 ("docs: pdfdocs: One-half spacing for CJK translations") - 788d28a25799 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts") - 29ac9822358f ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks") - 7c5c18bdb656 ("docs: pdfdocs: Fix typo in CJK-language specific font settings") - aa872e0647dc ("docs: pdfdocs: Adjust \headheight for fancyhdr") - 8716ef413aa5 ("docs: pdfdocs: Tweak width params of TOC") - 66939df53948 ("docs: pdfdocs: Switch default CJK font to KR variants") - 7b686a2ea1e4 ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles") - 5d9158e3c762 ("docs/translations: Skip CJK contents if suitable fonts not found") - b774cc46313b ("docs: pdfdocs: Move CJK monospace font setting to main conf.py") [1]: https://lore.kernel.org/all/87zgmr66cn.fsf@meer.lwn.net/ Suggested-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/aaa9dca1-27c0-c414-77f3-c5587db0cc5b@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Move CJK monospace font setting to main conf.pyAkira Yokosawa2022-02-151-0/+8
| | | | | | | | | | | | | | | | | | | As LaTeX macros for CJK font settings can have Latin-script font settings as well, settings under Documentation/translations/ can be moved to the main conf.py. By this change, translations.pdf built by top-level "make pdfdocs" can have properly aligned ascii-art diagrams except for Korean ones. For the reason of remaining misalignment in Korean diagrams, see changelog of commit a90dad8f610a ("docs: pdfdocs: Add conf.py local to translations for ascii-art alignment"). Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/eb87790a-03f4-9f29-c8a3-ef2c3e78ca18@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs/translations: Skip CJK contents if suitable fonts not foundAkira Yokosawa2022-02-151-4/+9
| | | | | | | | | | | | | | | | | | | | | | | | | | | | On systems without "Noto Sans CJK" fonts, CJK chapters in translations.pdf are full of "TOFU" boxes, with a long build time and a large log file containing lots of missing-font warnings. Avoid such waste of time and resources by skipping CJK chapters when CJK fonts are not available. To skip whole chapters, change the definition of \kerneldocBegin{SC|TC|KR|JP} commands so that they can have an argument to be ignored. This works as far as the argument (#1) is not used in the command. In place of skipped contents, put a note on skipped contents at the beginning of the PDF. Change the call sites in index.rst of CJK translations accordingly. When CJK fonts are available, existing command definitions with no argument just work. LaTeX engine will see additional pairs of "{" and "}", which add a level of grouping without having any effect on typesetting. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/3359ca41-b81d-b2c7-e437-7618efbe241d@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Enable CJKspace in TOC for Korean titlesAkira Yokosawa2022-02-151-1/+5
| | | | | | | | | | | | | | | | Korean (Hangul) titles in Table of Contents of translations.pdf don't have inter-phrase spaces. This is because the CJKspace option of xeCJK is disabled by default. Restore the spaces by enabling the option at the beginning of every document and disable it in the \kerneldocBegin{SC|TC|JP} commands. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/19141b3e-01d9-1f6d-5020-42fbda784831@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Switch default CJK font to KR variantsAkira Yokosawa2022-02-151-9/+14
| | | | | | | | | | | | | | | | | | | | | | | | xeCJK is enabled in Table of Contents (TOC) so that translations.pdf built by top-level "make pdfdocs" can have its TOC typeset properly. This causes quotation marks and apostrophe symbols appear too wide in Latin-script docs. This is because (1) Sphinx converts ASCII symbols into multi-byte UTF-8 ones in LaTeX and (2) in the SC variant of "Noto CJK" font families, those UTF-8 symbols have full-width glyph. The KR variant of the font families has half-width glyph for those symbols and TOC pages should look nicer when it is used instead. Switch the default CJK font families to the KR variant and teach xeCJK of those symbols' widths. To compensate the switch, teach xeCJK of the width in the SC and TC variants. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/0c8ea878-0a6f-ea01-ab45-4e66c5facee9@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Tweak width params of TOCAkira Yokosawa2022-02-151-0/+31
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Sphinx has its own set of width parameters of Table of Contents (TOC) for LaTeX defined in its class definition of sphinxmanual.cls. It also inherits parameters for chapter entries from report.cls of original LaTeX base. However, they are optimized assuming small documents with tens of pages and chapters/sections of less than 10. To cope with some of kernel-doc documents with more than 1000 pages and several tens of chapters/sections, definitions of those parameters need to be adjusted. Unfortunately, those parameters are hard coded in the class definitions and need low-level LaTeX coding tricks to redefine. As Sphinx 1.7.9 does not have \sphinxtableofcontentshook, which defines those parameters in later Sphinx versions, for compatibility with both pre-1.8 and later Sphinx versions, empty the hook altogether and redefine \@pnumwidth, \l@chapter, \l@section, and \@subsection commands originally defined in report.cls. Summary of parameter changes: Width of page number (\@pnumwidth): 1.55em -> 2.7em Width of chapter number: 1.5em -> 1.8em Indent of section number: 1.5em -> 1.8em Width of section number: 2.6em -> 3.2em Indent of subsection number: 4.1em -> 5em Width of subsection number: 3.5em -> 4.3em Notes: 1. Parameters for subsection become relevant only when ":maxdepth: 3" is specified under "toctree::" (e.g., RCU/index.rst). They can hold subsection numbers up to 5 digits such as "18.7.13" (in RCU.pdf). 2. Number of chapters in driver-api.pdf is getting closer to 100. When it reaches 100, another set of tweaks will be necessary. 3. The low-level LaTeX trick is mentioned in "Unofficial LaTeX2e reference manual" at: http://latexref.xyz/Table-of-contents-etc_002e.html Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/e52b4718-7909-25be-fbc1-76800aa62ae3@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: add support for RTD dark modeMauro Carvalho Chehab2021-12-101-1/+14
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* docs: set format for the classic modeMauro Carvalho Chehab2021-12-101-0/+30
| | | | | | | | | | | 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 <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/8889380606681a2b7033f73bed9717250302be2a.1638870323.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: allow to pass extra DOCS_CSS themes via makeMauro Carvalho Chehab2021-12-101-0/+7
| | | | | | | | | 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 <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/03d09bf41ad39aa0abfe2ea3c879b09aa3a0948d.1638870323.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: allow selecting a Sphinx themeMauro Carvalho Chehab2021-12-101-22/+30
| | | | | | | | | | | | | 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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/bd20adabfd428fd3cd0e69c2cf146aa354932936.1638870323.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: conf.py: fix support for Readthedocs v 1.0.0Mauro Carvalho Chehab2021-11-291-5/+10
| | | | | | | | | | | | | | | | | | | | | | | | 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: Hans Verkuil <hverkuil@xs4all.nl> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Tested-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/80009f0d17ea0840d81e7e16fff6e7677919fdfc.1638004294.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Adjust \headheight for fancyhdrAkira Yokosawa2021-10-121-0/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/c5a5577e-5de8-9cd4-9253-956ccc748417@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Fix typo in CJK-language specific font settingsAkira Yokosawa2021-09-061-2/+2
| | | | | | | | | | | | 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: e291ff6f5a03 ("docs: pdfdocs: Add CJK-language-specific font settings") Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/ad7615a5-f8fa-2bc3-de6b-7ed49d458964@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Teach xeCJK about character classes of quotation marksAkira Yokosawa2021-08-121-0/+4
| | | | | | | | | | | | | 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 <akiyks@gmail.com> Link: https://lore.kernel.org/r/0da9e3c5-2716-f576-1df5-2f28ea69f0e8@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Permit AutoFakeSlant for CJK fontsAkira Yokosawa2021-08-121-28/+28
| | | | | | | | | | 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 <akiyks@gmail.com> Link: https://lore.kernel.org/r/502335cc-9a95-3c2a-7744-6cc56ecaf628@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: One-half spacing for CJK translationsAkira Yokosawa2021-08-121-2/+10
| | | | | | | | | | | | | | | | | 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 <akiyks@gmail.com> Link: https://lore.kernel.org/r/547a1f1c-0bb5-20a7-ea0e-951bfc3c3925@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Preserve inter-phrase space in Korean translationsAkira Yokosawa2021-08-121-0/+1
| | | | | | | | | | 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 <akiyks@gmail.com> Link: https://lore.kernel.org/r/68de2e52-e6d1-3f01-c097-15ba7b28a319@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Choose Serif font as CJK mainfont if possibleAkira Yokosawa2021-08-121-5/+36
| | | | | | | | | | | | | | "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 <akiyks@gmail.com> Link: https://lore.kernel.org/r/5e454140-5d0c-35d4-8c31-3ffb2420793a@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Add CJK-language-specific font settingsAkira Yokosawa2021-08-121-1/+50
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 <akiyks@gmail.com> Link: https://lore.kernel.org/r/31906baf-7490-68cd-7153-4e4d320fb9b0@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Refactor config for CJK documentAkira Yokosawa2021-08-121-13/+9
| | | | | | | | | | | | | | | | 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: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/4baf88af-316d-8aee-240f-6ccbc20907d7@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: Take a little noise out of the build processJonathan Corbet2021-06-171-9/+0
| | | | | | | | 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: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Prevent column squeezing by tabularyAkira Yokosawa2021-06-011-0/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/277d68fa-c96a-0ccb-6ce0-4d314851d9fe@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: Activate exCJK only in CJK chaptersAkira Yokosawa2021-05-271-0/+13
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: Akira Yokosawa <akiyks@gmail.com> Tested-by: Wu XiangCheng <bobwxc@email.cn> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/lkml/2061da0a-6ab1-35f3-99c1-dbc415444f37@gmail.com Link: https://lore.kernel.org/r/83208ddc-5de9-b283-3fd6-92c635348ca0@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: conf.py: adjust the LaTeX document outputMauro Carvalho Chehab2021-03-081-12/+19
| | | | | | | | | | | | | | | | | | | | | | | Changeset f546ff0c0c07 ("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: f546ff0c0c07 ("Move our minimum Sphinx version to 1.7") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Documentation/conf.py | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) Link: https://lore.kernel.org/r/911fbac185dd09c7df715cf4153361b81f04b7ad.1614787053.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Fix unaesthetic indentationMatthew Wilcox2021-02-221-2/+1
| | | | | | | | | | | | | | | | | | | | 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: Jonathan Corbet <corbet@lwn.net>
* Move our minimum Sphinx version to 1.7Jonathan Corbet2021-02-011-72/+3
| | | | | | | 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: Jonathan Corbet <corbet@lwn.net>
* docs: Note that sphinx 1.7 will be required soonJonathan Corbet2020-12-111-0/+3
| | | | | | | The time has come to drop support for some truly ancient versions of sphinx; put in a warning now. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: admin-guide: add a features listMauro Carvalho Chehab2020-12-031-1/+1
| | | | | | | | Add a feature list matrix at the admin-guide. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/f6c1e366fbc7ce1c9c94c7dc6c7852c6377cc0be.1606748711.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Merge tag 'docs-5.10-warnings' of git://git.lwn.net/linuxLinus Torvalds2020-11-031-1/+1
|\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Pull documentation build warning fixes from Jonathan Corbet: "This contains a series of warning fixes from Mauro; once applied, the number of warnings from the once-noisy docs build process is nearly zero. Getting to this point has required a lot of work; once there, hopefully we can keep things that way. I have packaged this as a separate pull because it does a fair amount of reaching outside of Documentation/. The changes are all in comments and in code placement. It's all been in linux-next since last week" * tag 'docs-5.10-warnings' of git://git.lwn.net/linux: (24 commits) docs: SafeSetID: fix a warning amdgpu: fix a few kernel-doc markup issues selftests: kselftest_harness.h: fix kernel-doc markups drm: amdgpu_dm: fix a typo gpu: docs: amdgpu.rst: get rid of wrong kernel-doc markups drm: amdgpu: kernel-doc: update some adev parameters docs: fs: api-summary.rst: get rid of kernel-doc include IB/srpt: docs: add a description for cq_size member locking/refcount: move kernel-doc markups to the proper place docs: lockdep-design: fix some warning issues MAINTAINERS: fix broken doc refs due to yaml conversion ice: docs fix a devlink info that broke a table crypto: sun8x-ce*: update entries to its documentation net: phy: remove kernel-doc duplication mm: pagemap.h: fix two kernel-doc markups blk-mq: docs: add kernel-doc description for a new struct member docs: userspace-api: add iommu.rst to the index file docs: hwmon: mp2975.rst: address some html build warnings docs: net: statistics.rst: remove a duplicated kernel-doc docs: kasan.rst: add two missing blank lines ...
| * sphinx: conf.py: properly handle Sphinx 4.0Mauro Carvalho Chehab2020-10-281-1/+1
| | | | | | | | | | | | | | | | | | One of the checks for Sphinx 3+ is broken, causing some C warnings to return back with Sphinx 4.0.x. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/d5abc30056dafeec0778a46263a45401bdc7f11e.1603791716.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* | docs: add ABI documentation to the admin-guide bookMauro Carvalho Chehab2020-10-301-1/+2
|/ | | | | | | | | | | | | | 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: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/5651482b06500e69a1acdf92152f90a203e6521d.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
* docs: conf.py: change the Sphinx 3.x+ textMauro Carvalho Chehab2020-10-151-2/+2
| | | | | | | | | | | | 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 <mchehab+huawei@kernel.org>
* docs: conf.py: fix c:function support with Sphinx 3.xMauro Carvalho Chehab2020-10-151-3/+62
| | | | | | | | | | | | 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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
* Make the docs build "work" with Sphinx 3.xJonathan Corbet2020-09-041-1/+14
| | | | | | | | 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: Jonathan Corbet <corbet@lwn.net>
* Replace HTTP links with HTTPS ones: documentationAlexander A. Klimov2020-06-081-1/+1
| | | | | | | | | | | | | | | | | | | 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: Jonathan Corbet <corbet@lwn.net>
* docs: LaTeX/PDF: drop list of documentsMauro Carvalho Chehab2020-04-201-38/+0
| | | | | | | | | | | | | | | | The building system can auto-generate a list of documents since commit: 9d42afbe6bd4 ("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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/9345dba7164497dbf28578f6ec271e479379610c.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: conf.py: avoid thousands of duplicate label warning on SphinxMauro Carvalho Chehab2020-03-201-0/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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: 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/74f4d8d91c648d7101c45b4b99cc93532f4dadc6.1584716446.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: fix reference to core-api/namespaces.rstJonathan Corbet2020-03-191-1/+1
| | | | | | | | | | 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: fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/") Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* doc-rst: Programmatically render MAINTAINERS into ReSTKees Cook2019-10-021-1/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 additionally comma-separated. For example: SECURE COMPUTING Mail: Kees Cook <keescook@chromium.org> Reviewer: Andy Lutomirski <luto@amacapital.net>, Will Drewry <wad@chromium.org> SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git seccomp Status: Supported Files: kernel/seccomp.c include/uapi/linux/seccomp.h include/linux/seccomp.h tools/testing/selftests/seccomp/* tools/testing/selftests/kselftest_harness.h userspace-api/seccomp_filter Content regex: \bsecure_computing \bTIF_SECCOMP\b Signed-off-by: Kees Cook <keescook@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: conf.py: only use CJK if the font is availableMauro Carvalho Chehab2019-07-171-2/+11
| | | | | | | | | | | | | 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>
* docs: conf.py: add CJK package needed by translationsMauro Carvalho Chehab2019-07-171-0/+4
| | | | | | | 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 <mchehab+samsung@kernel.org>
* docs: pdf: add all Documentation/*/index.rst to PDF outputMauro Carvalho Chehab2019-07-171-0/+15
| | | | | | | | | | | | | | | 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: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
* Disable Sphinx SmartyPants in HTML outputStephen Kitt2019-06-301-1/+1
| | | | | | | | | | | | | 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: Jonathan Corbet <corbet@lwn.net>
* Docs: An initial automarkup extension for sphinxJonathan Corbet2019-06-261-1/+2
| | | | | | | 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: Jonathan Corbet <corbet@lwn.net>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-06 05:43:59 +0000