- Oct 13, 2022
-
-
Jonathan Corbet authored
We don't default to the RTD theme anymore, so sphinx-pre-install need not insist on installing it. Acked-by:
Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
- Aug 18, 2022
-
-
Akira Yokosawa authored
On distros whose texlive packaging is fine-grained, texlive-xecjk can be installed/removed independently of other texlive packages. Conditionally loading xeCJK depending only on the existence of the "Noto Sans CJK SC" font might end up in xelatex error of "xeCJK.sty not found!". Improve the situation by testing existence of xeCJK.sty before loading it. This is useful on RHEL 9 and its clone distros where texlive-xecjk doesn't work at the moment due to a missing dependency [1]. "make pdfdocs" for non-CJK contents should work after removing texlive-xecjk. Link: [1] https://bugzilla.redhat.com/show_bug.cgi?id=2086254 Fixes: 398f7abd ("docs: pdfdocs: Pull LaTeX preamble part out of conf.py") Cc: stable@vger.kernel.org # v5.18+ Signed-off-by:
Akira Yokosawa <akiyks@gmail.com> Acked-by:
-
- Jul 07, 2022
-
-
Jonathan Corbet authored
The automarkup code tries to look up symbols once as a function, and once as a macro. The Sphinx C domain code, though, totally ignores that distinction and will return the same results either way. So just look things up once and be done with it; the resulting output does not change, but htmldocs build time drops by about 5%. Tested-by:
-
Jonathan Corbet authored
The automarkup code tries to create a lot of cross-references that don't exist. Cross-reference lookups are expensive, especially in later versions of Sphinx, so there is value in avoiding unnecessary ones. Remember attempts that failed and do not retry them. This improves the htmldocs build time by 5-10% depending on the phase of the moon and other factors. Tested-by:
-
- May 17, 2022
-
-
Akira Yokosawa authored
It turns out that networking.pdf has exceeded 100 chapters and titles of chapters >= 100 collide with their counts in its table of contents (TOC). Increase relevant params by 0.6em in the preamble to avoid such ugly collisions. While at it, fix a typo in comment (subsection). Signed-off-by:
-
- Mar 30, 2022
-
-
Akira Yokosawa authored
jinja2 release 3.1.0 (March 24, 2022) broke Sphinx<4.0. This looks like the result of deprecating Python 3.6. It has been tested against Sphinx 4.3.0 and later. Setting an upper limit of <3.1 to junja2 can unbreak Sphinx<4.0 including Sphinx 2.4.4. Signed-off-by:
-
- Mar 28, 2022
-
-
Mauro Carvalho Chehab authored
In order to make it more standard and ReST compatible, change the meta-tag used with --enable-lineno from: #define LINENO to .. LINENO In practice, no functional changes. Signed-off-by: -
Mauro Carvalho Chehab authored
In order to make it more standard and ReST compatible, change the meta-tag used with --enable-lineno from: #define LINENO to .. LINENO In practice, no functional changes. Signed-off-by:
-
Mauro Carvalho Chehab authored
The files included by kernel-include should be added as build dependencies, in order for sphinx-build to rebuild the corresponding docs if any changes at the included file happens. Signed-off-by:
-
Mauro Carvalho Chehab authored
Ensure that Sphinx-build will handle the files parsed by get_abi.pl as dependencies. This way, if they are touched, the ABI output will be regenerated. Reported-by:
Hans de Goede <hdegoede@redhat.com> Signed-off-by:
-
Mauro Carvalho Chehab authored
Ensure that the feature files will be regenerated if any changes happen at the Documentation/features files that were processed by gen_feat.pl. Signed-off-by:
-
Akira Yokosawa authored
SVG -> PDF conversion is not required in "make htmldocs". It is pointless to always warn of a missing converter. Demote the log message in setupTools() to verbose. For "make pdfdocs" (or "make latexdocs"), promote the dynamic message of "include SVG raw" to a warn. Expand the message and recommend installing Inkscape or ImageMagick. Fixes: 8ccd0569 ("docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion") Signed-off-by:
-
- Feb 24, 2022
-
-
Akira Yokosawa authored
Use past tense as the fonts can be installed after the fact. Add suggestion to install "Noto Sans CJK" and "Noto Serif CJK" font families. ("Noto Serif CJK" is optional.) Signed-off-by: -
Akira Yokosawa authored
Expand comments in LaTeX code and mention some of important points told in changelogs of conf.py changes. Hopefully they can help future contributors in this area. No code change involved. Signed-off-by:
-
Akira Yokosawa authored
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 3b4c9632 ("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: - f7ebe6b7 ("docs: Activate exCJK only in CJK chapters") - 0afd4df0 ("docs: pdfdocs: Prevent column squeezing by tabulary") - 659653c9 ("docs: pdfdocs: Refactor config for CJK document") - e291ff6f ("docs: pdfdocs: Add CJK-language-specific font settings") - 7eb368cc ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible") - 35382965 ("docs: pdfdocs: Preserve inter-phrase space in Korean translations") - 77abc2c2 ("docs: pdfdocs: One-half spacing for CJK translations") - 788d28a2 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts") - 29ac9822 ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks") - 7c5c18bd ("docs: pdfdocs: Fix typo in CJK-language specific font settings") - aa872e06 ("docs: pdfdocs: Adjust \headheight for fancyhdr") - 8716ef41 ("docs: pdfdocs: Tweak width params of TOC") - 66939df5 ("docs: pdfdocs: Switch default CJK font to KR variants") - 7b686a2e ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles") - 5d9158e3 ("docs/translations: Skip CJK contents if suitable fonts not found") - b774cc46 ("docs: pdfdocs: Move CJK monospace font setting to main conf.py") [1]: https://lore.kernel.org/all/87zgmr66cn.fsf@meer.lwn.net/ Suggested-by:
-
- Feb 10, 2022
-
-
Akira Yokosawa authored
Depending on its version, distro config, and system-setup type, inkscape(1) emits various warning messages which are harmless in command-line uses. List of such warning messages (incomplete, long ones wrapped): - Gtk-Message: hh:mm:ss.nnn: Failed to load module "canberra-gtk-module" - Unable to init server: Could not connect: Connection refused - Failed to get connection - ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_proxy_new_for_name: assertion 'connection != NULL' failed - ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_proxy_call: assertion 'DBUS_IS_G_PROXY (proxy)' failed - ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_connection_register_g_object: assertion 'connection != NULL' failed - ** (inkscape:xxx): WARNING **: hh:mm:ss.nnn: Fonts dir '/usr/share/inkscape/fonts' does not exist and will be ignored. To avoid unnecessary anxiety, capture the message and output it via kernellog.verbose or kernellog.warn depending on the exit code. Signed-off-by: -
Akira Yokosawa authored
Using convert(1) of ImageMagick for SVG -> PDF conversion results in PDFs containing raster (bitmap) images which sometimes look blurry. Ideally speaking, SVG to PDF conversion should retain vector graphics in SVG. rsvg-convert(1) can do such conversions with regard to SVG files generated by dot(1). Unfortunately, rsvg-convert(1) does not cover some of SVG features specific to Inkscape. inkscape(1) of Inkscape naturally covers such SVG features. So add a route in svg2pdf() so that inkscape(1) is used when it is available. Note: After this change, if you have Inkscape installed, ImageMagick nor librsvg are not required. Signed-off-by: -
Akira Yokosawa authored
To prevent any regression on existing build systems, limit the fallback of converting DOT -> raster PDF only when both of the following conditions are met. o dot(1) doesn't support -Tpdf o rsvg-convert(1) is not found While we are here, add kernellog.verbose messages related to rsvg-convert, 'dot -Tpdf', and 'dot -Tsvg' commands. Suggested-by:
-
Akira Yokosawa authored
On openSUSE, dot(1) command does not support direct PDF output. On other distros, generated PDF images have unnecessarily wide margins, especially for small graphs. By using dot(1) for DOT -> SVG, then rsvg-convert(1) for SVG -> PDF, more optimal PDF images can be obtained, with the bonus of improved portability across various distros. Add rules in kfigure.py so that the above mentioned route is taken when rsvg-convert(1) is available. Note that rsvg-convert(1) is recommended by sphinx_pre_install. So it is most likely that existing systems for building pdfdocs have rsvg-convert(1) installed. Note: SVG features supported by rsvg-convert(1) vary depending on its version and distro config. For example, the one found on Ubuntu Bionic (version 2.40.20) does poor job in rendering some of SVG files drawn by Inkscape. SVG files generated by dot(1) are converted nicely even with such old versions of rsvg-convert. So this change does not affect the quality of such figures in any way. Signed-off-by:
-
- Jan 07, 2022
-
-
James Clark authored
Since commit d18b0178 ("docs: Add automatic cross-reference for documentation pages"), references that were already explicitly defined with "ref:" and referred to other pages with a path have been doubled. This is reported as the following error by Firefox: Start tag "a" seen but an element of the same type was already open. End tag "a" violates nesting rules. As well as the invalid HTML, this also obscures the URI fragment links to subsections because the second link overrides the first. For example on the page admin-guide/hw-vuln/mds.html the last link should be to the "Default Mitigations" subsection using a # URI fragment: admin-guide/hw-vuln/l1tf.html#default-mitigations But it is obsured by a second link to the whole page: admin-guide/hw-vuln/l1tf.html The full HTML with the double <a> tags looks like this: <a class="reference internal" href="l1tf.html#default-mitigations"> <span class="std std-ref"> <a class="reference internal" href="l1tf.html"> <span class="doc">L1TF - L1 Terminal Fault</span> </a> </span> </a> After this commit, there is only a single link: <a class="reference internal" href="l1tf.html#default-mitigations"> <span class="std std-ref">Documentation/admin-guide/hw-vuln//l1tf.rst</span> </a> Now that the second link is removed, the browser correctly jumps to the default-mitigations subsection when clicking the link. The fix is to check that nodes in the document to be modified are not already references. A reference is counted as any text that is a descendant of a reference type node. Only plain text should be converted to new references, otherwise the doubling occurs. Testing ======= * Test that the build stdout is the same (ignoring ordering), and that no new warnings are printed. * Diff all .html files and check that the only modifications occur to the bad double links. * The auto linking of bare references to pages without "ref:" is still working. Fixes: d18b0178 ("docs: Add automatic cross-reference for documentation pages") Reviewed-by:
Nícolas F. R. A. Prado <n@nfraprado.net> Signed-off-by:
James Clark <james.clark@arm.com> Link: https://lore.kernel.org/r/20220105143640.330602-2-james.clark@arm.com Signed-off-by:
-
- Dec 23, 2021
-
-
Randy Dunlap authored
Use "its" for possessive form instead of the contraction "it's". Signed-off-by:
Randy Dunlap <rdunlap@infradead.org> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Link: https://lore.kernel.org/r/20211222062354.23224-1-rdunlap@infradead.org Signed-off-by:
-
- Aug 12, 2021
-
-
Akira Yokosawa authored
sphinx_rtd_theme 0.5.2 has "docutils<0.17" in its requirements. docutils 0.17 released this April caused regression in sphinx_rtd_theme 0.5.1 [1]. By removing docutils and moving sphinx_rtd_theme before Sphinx in requirements.txt, the requirement of "docutils<0.17" can be met naturally. [1]: https://github.com/readthedocs/sphinx_rtd_theme/issues/1112 Signed-off-by:
-
- Mar 07, 2021
-
-
Bhaskar Chowdhury authored
s/automaticly/automatically/ s/buidler/builder/ ..and a sentence construction fix. Signed-off-by:
Bhaskar Chowdhury <unixbhaskar@gmail.com> Acked-by:
-
- Feb 04, 2021
-
-
Nícolas F. R. A. Prado authored
Previously, a cross-reference to another document could only be created by writing the full path to the document starting from the Documentation/ directory. Extend this to also allow relative paths to be used. A relative path would be just the path, like ../filename.rst, while the absolute path still needs to start from Documentation, like Documentation/filename.rst. As part of this change, the .rst extension is now required for both types of paths, since not requiring it would cause the regex to be too generic. Suggested-by:
Nícolas F. R. A. Prado <nfraprado@protonmail.com> Link: https://lore.kernel.org/r/20210128010028.58541-2-nfraprado@protonmail.com [jc: Tweaked the regex to recognize .txt too] Signed-off-by:
-
- Feb 02, 2021
-
-
Jonathan Corbet authored
The kernel build system as a whole is dropping support for Python 2, so we should do the same. The effects are rather small, especially considering that much of the deleted code was not doing anything under any version of Python anyway. 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 10, 2020
-
-
JaeSang Yoo authored
On the update of Sphinx version to 2.4.4, the "six" library won't be installed automatically. (which is required by kfigure.py) Main reason of this issue were occurred by the requirements changed from the sphinx library. In Sphinx v1.7.9, six was listed on the install_requires, but it has been removed since 2.x The kfigure.py uses six library explicitly, adding six to requirements.txt seems reasonable Signed-off-by:
JaeSang Yoo <jsyoo5b@gmail.com> Reviewed-by:
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/20201208014628.GA1361@JSYoo5B-Base.localdomain Signed-off-by:
-
- Dec 08, 2020
-
-
Fiona Behrens authored
Change every shebang which does not need an argument to use /usr/bin/env. This is needed as not every distro has everything under /usr/bin, sometimes not even bash. Signed-off-by:
Finn Behrens <me@kloenk.de> Signed-off-by:
Masahiro Yamada <masahiroy@kernel.org>
-
- Dec 03, 2020
-
-
Mauro Carvalho Chehab authored
The feature files have a special well-defined format. Add a script that parses them, allowing to search for a feature and/or by an architecture and to produce ReST-compatible outputs. Signed-off-by:
-
- Nov 30, 2020
-
-
Nícolas F. R. A. Prado authored
Sphinx 3.1 introduced namespaces for C cross-references. With this, each C domain type/function declaration is put inside the namespace that was active at the time of its declaration. Add support for automatic cross-referencing inside C namespaces by checking whether the corresponding source file had a C namespace Sphinx directive, and if so, try cross-referencing inside of it before going to the global scope. This assumes there's only one namespace (if any) per rst file. Signed-off-by:
-
- Nov 03, 2020
-
-
Jonathan Corbet authored
It turns out that the Python 2 re module lacks the ASCII flag, so don't try to use it there. Fixes: f66e47f9 ("docs: automarkup.py: Fix regexes to solve sphinx 3 warnings") Reported-by:
Dafna Hirschfeld <dafna.hirschfeld@collabora.com> Signed-off-by:
-
- Oct 30, 2020
-
-
Mauro Carvalho Chehab authored
Now that the stable ABI files are compatible with ReST, parse them without converting complex descriptions as literal blocks nor escaping special characters. Please notice that escaping special characters will probably be needed at descriptions, at least for the asterisk character. Acked-by:
Greg Kroah-Hartman <gregkh@linuxfoundation.org>
-
Mauro Carvalho Chehab authored
The Sphinx docutils parser is lazy: if the content is bigger than a certain number of lines, it silenlty stops parsing it, producing an incomplete content. This seems to be worse on newer Sphinx versions, like 2.0. So, change the logic to parse the contents per input file. Acked-by:
-
Mauro Carvalho Chehab authored
Just like kernel-doc extension, we need to be able to identify what part of an imported document has issues, as reporting them as: get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation. Makes a lot harder for someone to fix. It should be noticed that it the line which will be reported is the line where the "What:" definition is, and not the line with actually has an error. Acked-by:
-
Mauro Carvalho Chehab authored
The same way kerneldoc.py needed changes to work with newer Sphinx, this script needs the same changes. While here, reorganize the include order to match kerneldoc.py. Acked-by:
-
Mauro Carvalho Chehab authored
The parser breaks with UTF-8 characters with Sphinx 1.4. Acked-by:
-
Mauro Carvalho Chehab authored
The ABI documentation is special: it is not plain text files, but, instead, files with an strict format, as specified by Documentation/ABI/README. Add a parser for it. Acked-by:
-
Mauro Carvalho Chehab authored
An extension may want to just inform about something. So, add support for it. Acked-by:
-
- Oct 15, 2020
-
-
Mauro Carvalho Chehab authored
The :c:type:`foo` only works properly with structs before Sphinx 3.x. On Sphinx 3.x, structs should now be declared using the .. c:struct, and referenced via :c:struct tag. As we now have the automarkup.py macro, that automatically convert: struct foo into cross-references, let's get rid of that, solving several warnings when building docs with Sphinx 3.x. Reviewed-by: André Almeida <andrealmeid@collabora.com> # blk-mq.rst Reviewed-by: Takashi Iwai <tiwai@suse.de> # sound Reviewed-by:
Mike Rapoport <rppt@linux.ibm.com> Reviewed-by:
-
Sphinx 3 added support for declaring C macros with parameters using the :c:macro role. To support automarkup for both functions and parametrized macros using the same regex (words ending in ()), try to cross-reference to both, and only fall back to regular text if neither exist. Signed-off-by:
-
