summaryrefslogtreecommitdiff
path: root/Documentation/sphinx
AgeCommit message (Collapse)Author
2023-02-16docs: Use HTML comments for the kernel-toc SPDX lineJonathan Corbet
This line was initially placed in {# jinja2 comments #}, but that led to an "invalid token" complaint from spdxcheck.py. Rather than fix the script for a usage we'll likely never see anywhere else, just switch to an HTML comment, which spdxcheck.py thinks is fine. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2023-02-08docs: Add more information to the HTML sidebarJonathan Corbet
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>
2023-01-06docs: Fix the docs build with Sphinx 6.0Jonathan Corbet
Sphinx 6.0 removed the execfile_() function, which we use as part of the configuration process. They *did* warn us... Just open-code the functionality as is done in Sphinx itself. Tested (using SPHINX_CONF, since this code is only executed with an alternative config file) on various Sphinx versions from 2.5 through 6.0. Reported-by: Martin Liška <mliska@suse.cz> Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-10-13docs: sphinx-pre-install: don't require the RTD themeJonathan Corbet
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>
2022-08-18docs: kerneldoc-preamble: Test xeCJK.sty before loadingAkira Yokosawa
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: 398f7abdcb7e ("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: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/c24c2a87-70b2-5342-bcc9-de467940466e@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-07-07docs: automarkup: do not look up symbols twiceJonathan Corbet
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: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220630163630.714673-3-corbet@lwn.net Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-07-07docs: automarkup: track failed cross-reference attemptsJonathan Corbet
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: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220630163630.714673-2-corbet@lwn.net Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-05-17docs: pdfdocs: Add space for chapter counts >= 100 in TOCAkira Yokosawa
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: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/bdb60ba3-7813-47d0-74f9-7c31dd912d95@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-30docs: sphinx/requirements: Limit jinja2<3.1Akira Yokosawa
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: Akira Yokosawa <akiyks@gmail.com> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: stable@vger.kernel.org # v5.15+ Link: https://lore.kernel.org/r/7dbff8a0-f4ff-34a0-71c7-1987baf471f9@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28scripts/kernel-doc: change the line number meta infoMauro Carvalho Chehab
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 <mchehab@kernel.org> Link: https://lore.kernel.org/r/40725032b5a4a33db740bf1de397523af958ff8a.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28scripts/get_abi: change the file/line number meta infoMauro Carvalho Chehab
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 <mchehab@kernel.org> Link: https://lore.kernel.org/r/125ffd31fbc77ad9eee4d6906e1830b8162fa6ca.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28docs: kernel_include.py: add sphinx build dependenciesMauro Carvalho Chehab
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 <mchehab@kernel.org> Link: https://lore.kernel.org/r/d30fc4fa422a13b7e1623d690945c46b58a55e79.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28docs: kernel_abi.py: add sphinx build dependenciesMauro Carvalho Chehab
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 <mchehab@kernel.org> Link: https://lore.kernel.org/r/10bc3d3bc74f514a539cd3b48b9d287d2b6f99e2.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28docs: kernel_feat.py: add build dependenciesMauro Carvalho Chehab
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: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/5cdf7a8300019129dcc09d4c2557f75908754445.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28docs: kfigure.py: Don't warn of missing PDF converter in 'make htmldocs'Akira Yokosawa
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: 8ccd05697a9d ("docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion") Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: linux-doc@vger.kernel.org Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/c80e1481-10d4-7151-fe59-e846259eb0d4@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24Reword note on missing CJK fontsAkira Yokosawa
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 <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/dfefa601-c58d-c86c-953f-5e4454db9409@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24docs: kerneldoc-preamble.sty: Expand comments in LaTeX codeAkira Yokosawa
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 <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/bce9261b-1950-3146-07b2-07bd2ec79158@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24docs: pdfdocs: Pull LaTeX preamble part out of conf.pyAkira Yokosawa
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>
2022-02-09docs: sphinx/kfigure.py: Delegate inkscape msg to kernellog.verboseAkira Yokosawa
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 <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/e26a7b53-9155-8394-4a31-6006379b65a5@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-09docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversionAkira Yokosawa
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 <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/3eea2a8d-c52d-ee07-cf7b-83784c6f6e4b@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-09docs: sphinx/kfigure.py: Add check of 'dot -Tpdf'Akira Yokosawa
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: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/e76f61e1-7366-ba00-b119-8ea6a2499861@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-09docs: sphinx/kfigure.py: Use rsvg-convert(1) for DOT -> PDF conversionAkira Yokosawa
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: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/15b56dd3-081a-2469-c3a4-dfc1ca4c6c2d@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-01-07docs: automarkup.py: Fix invalid HTML link output and broken URI fragmentsJames Clark
Since commit d18b01789ae5 ("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: d18b01789ae5 ("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: Jonathan Corbet <corbet@lwn.net>
2021-12-23Documentation/sphinx: fix typos of "its"Randy Dunlap
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: Jonathan Corbet <corbet@lwn.net>
2021-08-12docs: sphinx-requirements: Move sphinx_rtd_theme to topAkira Yokosawa
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: Akira Yokosawa <akiyks@gmail.com> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/75f14c88-6091-1072-41cb-16b886aee5a0@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-03-06docs: sphinx: Fix couple of spellings in the file rstFlatTable.pyBhaskar Chowdhury
s/automaticly/automatically/ s/buidler/builder/ ..and a sentence construction fix. Signed-off-by: Bhaskar Chowdhury <unixbhaskar@gmail.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/20210301201052.11067-1-unixbhaskar@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-02-04docs: Enable usage of relative paths to docs on automarkupNícolas F. R. A. Prado
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: Jonathan Corbet <corbet@lwn.net> Signed-off-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: Jonathan Corbet <corbet@lwn.net>
2021-02-01Docs: drop Python 2 supportJonathan Corbet
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: Jonathan Corbet <corbet@lwn.net>
2021-02-01Move our minimum Sphinx version to 1.7Jonathan Corbet
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>
2020-12-22Merge tag 'kbuild-v5.11' of ↵Linus Torvalds
git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild Pull Kbuild updates from Masahiro Yamada: - Use /usr/bin/env for shebang lines in scripts - Remove useless -Wnested-externs warning flag - Update documents - Refactor log handling in modpost - Stop building modules without MODULE_LICENSE() tag - Make the insane combination of 'static' and EXPORT_SYMBOL an error - Improve genksyms to handle _Static_assert() * tag 'kbuild-v5.11' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild: Documentation/kbuild: Document platform dependency practises Documentation/kbuild: Document COMPILE_TEST dependencies genksyms: Ignore module scoped _Static_assert() modpost: turn static exports into error modpost: turn section mismatches to error from fatal() modpost: change license incompatibility to error() from fatal() modpost: turn missing MODULE_LICENSE() into error modpost: refactor error handling and clarify error/fatal difference modpost: rename merror() to error() kbuild: don't hardcode depmod path kbuild: doc: document subdir-y syntax kbuild: doc: clarify the difference between extra-y and always-y kbuild: doc: split if_changed explanation to a separate section kbuild: doc: merge 'Special Rules' and 'Custom kbuild commands' sections kbuild: doc: fix 'List directories to visit when descending' section kbuild: doc: replace arch/$(ARCH)/ with arch/$(SRCARCH)/ kbuild: doc: update the description about kbuild Makefiles Makefile.extrawarn: remove -Wnested-externs warning tweewide: Fix most Shebang lines
2020-12-09docs: update requirements to install six moduleJaeSang Yoo
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: Jonathan Corbet <corbet@lwn.net>
2020-12-08tweewide: Fix most Shebang linesFinn Behrens
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>
2020-12-03sphinx: kernel_feat.py: add a script to parse feature filesMauro Carvalho Chehab
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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/bb2e51e5aa883e2583a4a6280f1c1b391bd8ef4c.1606748711.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-11-30docs: automarkup.py: Allow automatic cross-reference inside C namespaceNícolas F. R. A. Prado
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: Nícolas F. R. A. Prado <nfraprado@protonmail.com> Link: https://lore.kernel.org/r/20201117021107.214704-1-nfraprado@protonmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-11-03Merge tag 'docs-5.10-3' of git://git.lwn.net/linuxLinus Torvalds
Pull documentation fixes from Jonathan Corbet: "A small number of fixes, plus a build tweak to respect the desire for silence in V=0 builds" * tag 'docs-5.10-3' of git://git.lwn.net/linux: docs: fix automarkup regression on Python 2 documentation: arm: sunxi: add Allwinner H6 documents scripts: kernel-doc: split typedef complex regex scripts: kernel-doc: fix typedef parsing docs: Makefile: honor V=0 for docs building
2020-11-03docs: fix automarkup regression on Python 2Jonathan Corbet
It turns out that the Python 2 re module lacks the ASCII flag, so don't try to use it there. Fixes: f66e47f98c1e ("docs: automarkup.py: Fix regexes to solve sphinx 3 warnings") Reported-by: Dafna Hirschfeld <dafna.hirschfeld@collabora.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-10-30docs: ABI: make it parse ABI/stable as ReST-compatible filesMauro Carvalho Chehab
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: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/59ccbaa75ff05f23e701dd9a0bbe118e9343a553.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-10-30docs: kernel_abi.py: Handle with a lazy Sphinx parserMauro Carvalho Chehab
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: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/4659b60795739308e34d2d00c57ee0742a9cd2ab.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-10-30docs: kernel_abi.py: use --enable-lineno for get_abi.plMauro Carvalho Chehab
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: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/d6155ab16fb7631f2fa8e7a770eae72f24bf7cc5.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-10-30docs: kernel_abi.py: make it compatible with Sphinx 1.7+Mauro Carvalho Chehab
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: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/f2b25caef5db7738629773a03463908d3b39b83a.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-10-30docs: kernel_abi.py: fix UTF-8 supportMauro Carvalho Chehab
The parser breaks with UTF-8 characters with Sphinx 1.4. Acked-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/9e7c8e3b0efaa1ae0536da6493ab438bd3f9fe58.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-10-30docs: kernel_abi.py: add a script to parse ABI documentationMauro Carvalho Chehab
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: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/48abf1a410237e63f85354a8cd7027fdf25657bf.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-10-30docs: kernellog.py: add support for info()Mauro Carvalho Chehab
An extension may want to just inform about something. So, add support for it. Acked-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/0ddebd8677605d789d53433c8a5344c68da82a73.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-10-15docs: get rid of :c:type explicit declarations for structsMauro Carvalho Chehab
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: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15docs: automarkup.py: Add cross-reference for parametrized C macrosNícolas F. R. A. Prado
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: Nícolas F. R. A. Prado <nfraprado@protonmail.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15docs: automarkup.py: Skip C reserved words when cross-referencingNícolas F. R. A. Prado
With the transition to Sphinx 3, new warnings were caused by automarkup, exposing bugs in the name matching. When automarkup parsed a text like "struct struct" in the documentation, it tried to cross-reference to a "struct" symbol, which is recognized as a C reserved word by Sphinx 3, generating a warning. Add some C reserved words (only the ones that were causing warnings) to a list and skip them while trying to cross-reference. Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15docs: automarkup.py: Fix regexes to solve sphinx 3 warningsNícolas F. R. A. Prado
With the transition to Sphinx 3, new warnings were generated by automarkup, exposing bugs in the regexes. The warnings were caused by the expressions matching words in the translated versions of the documentation, since any unicode character was matched. Fix the regular expression by making the C regexes use ASCII and ensuring the expressions only match the beginning of words, in order to avoid warnings like this: WARNING: Unparseable C cross-reference: '调用debugfs_rename' That's probably due to the lack of using spaces between words on Chinese. Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15docs: automarkup.py: Use new C roles in Sphinx 3Nícolas F. R. A. Prado
While Sphinx 2 used a single c:type role for struct, union, enum and typedef, Sphinx 3 uses a specific role for each one. To keep backward compatibility, detect the Sphinx version and use the correct roles for that version. Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15docs: kerneldoc.py: add support for kerneldoc -nosymbolMauro Carvalho Chehab
Currently, there's no way to exclude identifiers from a kernel-doc markup. Add support for it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15docs: kerneldoc.py: append the name of the parsed doc fileMauro Carvalho Chehab
Finding where an error like this was generated: ../lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'kernel-api'. Can take some time, as there's no glue about what kernel-doc tag generated it. It is a way better to display it as: .../Documentation/core-api/kernel-api:171: ../lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'kernel-api'. Declaration is 'div_s64_rem'. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
generated by cgit v1.2.3-58-ga151 (git 2.39.0) at 2024-11-29 22:32:25 +0000