Commit graph

129 commits

Author SHA1 Message Date
Bjorn Helgaas
d56b699d76 Documentation: Fix typos
Fix typos in Documentation.

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Link: https://lore.kernel.org/r/20230814212822.193684-4-helgaas@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2023-08-18 11:29:03 -06:00
Jonathan Corbet
4e98799a70 docs: Use HTML comments for the kernel-toc SPDX line
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-16 16:06:44 -07:00
Jonathan Corbet
c404f5d4f0 docs: Add more information to the HTML sidebar
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-02-08 13:28:27 -07:00
Jonathan Corbet
0283189e8f docs: Fix the docs build with Sphinx 6.0
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>
2023-01-06 13:04:00 -07:00
Jonathan Corbet
df19817f3f docs: sphinx-pre-install: don't require the RTD theme
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-10-13 11:14:43 -06:00
Akira Yokosawa
cee7db1b02 docs: kerneldoc-preamble: Test xeCJK.sty before loading
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: 398f7abdcb ("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-08-18 11:27:55 -06:00
Jonathan Corbet
309027b57c docs: automarkup: do not look up symbols twice
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-07 12:57:55 -06:00
Jonathan Corbet
26c82972f2 docs: automarkup: track failed cross-reference attempts
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-07-07 12:57:48 -06:00
Akira Yokosawa
b86f46d5ce docs: pdfdocs: Add space for chapter counts >= 100 in TOC
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-05-17 13:41:26 -06:00
Akira Yokosawa
be78837ca3 docs: sphinx/requirements: Limit jinja2<3.1
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-30 13:44:54 -06:00
Mauro Carvalho Chehab
b79dfef0e2 scripts/kernel-doc: change the line number meta info
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-28 13:53:46 -06:00
Mauro Carvalho Chehab
92b6de17b2 scripts/get_abi: change the file/line number meta info
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-28 13:53:46 -06:00
Mauro Carvalho Chehab
bcf0a536bf docs: kernel_include.py: add sphinx build dependencies
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-28 13:53:46 -06:00
Mauro Carvalho Chehab
b4541803d8 docs: kernel_abi.py: add sphinx build dependencies
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-28 13:53:46 -06:00
Mauro Carvalho Chehab
85999f0314 docs: kernel_feat.py: add build dependencies
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-28 13:53:46 -06:00
Akira Yokosawa
d987d5ae51 docs: kfigure.py: Don't warn of missing PDF converter in 'make htmldocs'
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: 8ccd05697a ("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-03-28 13:52:51 -06:00
Akira Yokosawa
96c7f3b53c Reword note on missing CJK fonts
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-24 12:26:13 -07:00
Akira Yokosawa
7cee33ce23 docs: kerneldoc-preamble.sty: Expand comments in LaTeX code
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-24 12:26:13 -07:00
Akira Yokosawa
398f7abdcb docs: pdfdocs: Pull LaTeX preamble part out of conf.py
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 3b4c963243 ("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:

  - f7ebe6b769 ("docs: Activate exCJK only in CJK chapters")
  - 0afd4df0d1 ("docs: pdfdocs: Prevent column squeezing by tabulary")
  - 659653c9e5 ("docs: pdfdocs: Refactor config for CJK document")
  - e291ff6f5a ("docs: pdfdocs: Add CJK-language-specific font settings")
  - 7eb368cc31 ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible")
  - 35382965bd ("docs: pdfdocs: Preserve inter-phrase space in Korean translations")
  - 77abc2c230 ("docs: pdfdocs: One-half spacing for CJK translations")
  - 788d28a257 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts")
  - 29ac982235 ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks")
  - 7c5c18bdb6 ("docs: pdfdocs: Fix typo in CJK-language specific font settings")
  - aa872e0647 ("docs: pdfdocs: Adjust \headheight for fancyhdr")
  - 8716ef413a ("docs: pdfdocs: Tweak width params of TOC")
  - 66939df539 ("docs: pdfdocs: Switch default CJK font to KR variants")
  - 7b686a2ea1 ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles")
  - 5d9158e3c7 ("docs/translations: Skip CJK contents if suitable fonts not found")
  - b774cc4631 ("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-24 12:26:13 -07:00
Akira Yokosawa
f30a7ac8c6 docs: sphinx/kfigure.py: Delegate inkscape msg to kernellog.verbose
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-09 17:00:41 -07:00
Akira Yokosawa
8ccd05697a docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion
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-09 17:00:41 -07:00
Akira Yokosawa
ecf5fb58cd docs: sphinx/kfigure.py: Add check of 'dot -Tpdf'
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-09 17:00:41 -07:00
Akira Yokosawa
c9edbe1eb9 docs: sphinx/kfigure.py: Use rsvg-convert(1) for DOT -> PDF conversion
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-02-09 17:00:41 -07:00
James Clark
7cc4c09269 docs: automarkup.py: Fix invalid HTML link output and broken URI fragments
Since commit d18b01789a ("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: d18b01789a ("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>
2022-01-07 09:32:58 -07:00
Randy Dunlap
32211146e1 Documentation/sphinx: fix typos of "its"
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-12-23 12:42:47 -07:00
Akira Yokosawa
37397b092e docs: sphinx-requirements: Move sphinx_rtd_theme to top
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-08-12 09:15:38 -06:00
Bhaskar Chowdhury
abe4a3996e docs: sphinx: Fix couple of spellings in the file rstFlatTable.py
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-03-06 17:36:50 -07:00
Nícolas F. R. A. Prado
ea1d838980 docs: Enable usage of relative paths to docs on automarkup
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-04 16:23:43 -07:00
Jonathan Corbet
4217e5074f Docs: drop Python 2 support
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-01 17:17:14 -07:00
Jonathan Corbet
f546ff0c0c Move our minimum Sphinx version to 1.7
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>
2021-02-01 16:29:12 -07:00
Linus Torvalds
7b95f0563a Kbuild updates for v5.11
- 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()
 -----BEGIN PGP SIGNATURE-----
 
 iQJJBAABCgAzFiEEbmPs18K1szRHjPqEPYsBB53g2wYFAl/iIY8VHG1hc2FoaXJv
 eUBrZXJuZWwub3JnAAoJED2LAQed4NsGbfsP+gMv3F+ztqfYNoMNmZcj+fLh4zrA
 8I3d0t0AoxovV1bsyVDk9nebsYLbDdsyCdHM1ZNFAFEpf9QLL8sxtpHvaaxy+rCq
 PCmy+E6iO5B91oORhuqpYpcmmgPHf4RrpUcnEEiWOMrHE5giYbXz3AiqGAt/88J5
 Y8yaPCQVhNJNkx73KHCMYLVp97xPGa5HvNrcskAueA8uG+FCRDFaIqFX+OYbGnmC
 /3kVAJmX6i2kNPzvnXpAW6mTbI/z7+s/k5yRbEFYNUtJqN+BfaFadV8pyOGXQr1T
 fwXVtXdWqVg7rbqupyVYItLHaOq2RBm4PJuee/8s7ooBI1y7U6N0HZCj+jES92ML
 wuqEyED+lLzmxRyfhmrFH/5XhxacciO7dQb9Woe5FQ6QOm+tQPtwCnxwrSSAK4XU
 k7CsJ+OMJI+JulFrgPuC/rcESjTAsgL2j4SDhsO0GLV+Qb/P9kXR88jt5eJygmSx
 xZWpI+FUUY/Ihw648i2pkHGS/NmfOrT78X4nvbOWMDKOV02NEoMmLDYnZPUIoetn
 yUo8+xSBp6n3aTy5TDtrMblNRUJwL9OzDlDiEjsPtNUJZ6sdQzFRsxJ7+FCw2Ley
 rKN2r+i5FdyAq0LLHDhoEcJxFY7cj+yAsd0QqtBb0NZLgLsaPiP7w45CXRNpqkWG
 BbK+F1E9jP8VfiZu
 =+27V
 -----END PGP SIGNATURE-----

Merge tag 'kbuild-v5.11' of 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-22 14:02:39 -08:00
JaeSang Yoo
ab9e1ac49b docs: update requirements to install six module
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-09 17:27:47 -07:00
Finn Behrens
c25ce589dc tweewide: Fix most Shebang lines
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-08 23:30:04 +09:00
Mauro Carvalho Chehab
b97212255f sphinx: kernel_feat.py: add a script to parse feature files
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-12-03 15:10:14 -07:00
Nícolas F. R. A. Prado
fb568273c0 docs: automarkup.py: Allow automatic cross-reference inside C namespace
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-30 10:54:33 -07:00
Linus Torvalds
ce2e33ba41 A small number of fixes, plus a build tweak to respect the desire for
silence in V=0 builds.
 -----BEGIN PGP SIGNATURE-----
 
 iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAl+hdscPHGNvcmJldEBs
 d24ubmV0AAoJEBdDWhNsDH5YOHYH/jMaHkXTOVQZIFouNn1nSymdk7ErTEinkVKu
 l2E1teuyqY6nrZVWut8dtJEPSiMFxkjXP7qyvG3kAUEOz7axi0XhTPudLihBMj2N
 xqUuOGoOpLhEa/F2jm1sDbS0NFmYtWkur/kZB4ibMVa5dp1jj61s1qAADhPDUXzH
 J7H2AIGpVJkQyzFjslI7thwFGSR80ID49zVnAAI5b+MCayofij3Tn/wqdCGjecNa
 5e/qPBxM/E8XkMq0mxUGvOvlDQd01LpCkr01wJeU+lgm3J48iGPnRqiRtae4kSMv
 fYIaNvClhYARzMOwi4ExDJHUa0cp99FPXJ3enqsrEqo9yLkUw1I=
 =PbGq
 -----END PGP SIGNATURE-----

Merge tag 'docs-5.10-3' of git://git.lwn.net/linux

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-03 09:57:30 -08:00
Jonathan Corbet
4f3e69060d docs: fix automarkup regression on Python 2
It turns out that the Python 2 re module lacks the ASCII flag, so don't try
to use it there.

Fixes: f66e47f98c ("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-11-03 08:22:00 -07:00
Mauro Carvalho Chehab
642514df1b docs: ABI: make it parse ABI/stable as ReST-compatible files
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-30 13:07:02 +01:00
Mauro Carvalho Chehab
3c543d2989 docs: kernel_abi.py: Handle with a lazy Sphinx parser
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-30 13:02:26 +01:00
Mauro Carvalho Chehab
997b7c8b4a docs: kernel_abi.py: use --enable-lineno for get_abi.pl
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-30 13:02:26 +01:00
Mauro Carvalho Chehab
c830fa9a4d docs: kernel_abi.py: make it compatible with Sphinx 1.7+
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-30 13:02:26 +01:00
Mauro Carvalho Chehab
823830d406 docs: kernel_abi.py: fix UTF-8 support
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-30 13:02:26 +01:00
Mauro Carvalho Chehab
9ca876f963 docs: kernel_abi.py: add a script to parse ABI documentation
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-30 13:02:26 +01:00
Mauro Carvalho Chehab
678a63f988 docs: kernellog.py: add support for info()
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-30 13:02:26 +01:00
Mauro Carvalho Chehab
9303c9d5e9 docs: get rid of :c:type explicit declarations for structs
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-15 07:49:40 +02:00
Nícolas F. R. A. Prado
c51d9b046f docs: automarkup.py: Add cross-reference for parametrized C macros
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-15 07:49:38 +02:00
Nícolas F. R. A. Prado
3050edfd79 docs: automarkup.py: Skip C reserved words when cross-referencing
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-15 07:49:38 +02:00
Nícolas F. R. A. Prado
f66e47f98c docs: automarkup.py: Fix regexes to solve sphinx 3 warnings
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-15 07:49:38 +02:00
Nícolas F. R. A. Prado
06dc65b0fa docs: automarkup.py: Use new C roles in Sphinx 3
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-15 07:49:38 +02:00
Mauro Carvalho Chehab
2791f47d26 docs: kerneldoc.py: add support for kerneldoc -nosymbol
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-15 07:49:38 +02:00