Commit Graph

44 Commits

Author SHA1 Message Date
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
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
Jonathan Corbet 2f444efdaa docs: Don't push Sphinx upgrades quite so readily
The sphinx-pre-install script will put out a verbose message recommending
an upgrade for anybody running less than 2.4.4 - which was only released in
March.  So *everybody* will see that warning at this point.  Let's only
warn if the user is below our generally recommended version (1.7.9
currently).

It might be good to put out a warning if people are explicitly making PDF
files, but would need to be done in a different place and relatively few
people do that.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-06-26 09:31:53 -06:00
Mauro Carvalho Chehab ec43a27fff scripts: sphinx-pre-install: change the output order
When the script detects the need for an upgrade, it will
print either a warning or a note.

Let's change a little bit the order where messages will be
displayed, in order to make easier for the user to identify
the more important messages.

It should now be like this:

	Detected OS: Fedora release 31 (Thirty One).
	Sphinx version: 1.7.9

	Note: It is recommended at least Sphinx version 2.4.4 if you need PDF support.
	To upgrade Sphinx, use:

		/usr/bin/python3 -m venv sphinx_2.4.4
		. sphinx_2.4.4/bin/activate
		pip install -r ./Documentation/sphinx/requirements.txt

	If you want to exit the virtualenv, you can use:
		deactivate

All optional dependencies are met.
Needed package dependencies are met.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/20200421182758.04e0a53e@coco.lan
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-28 12:52:52 -06:00
Mauro Carvalho Chehab 412b09ddad scripts: sphinx-pre-install: fix a bug when using with venv
When python3 creates a venv, it adds python into it!

This causes any upgrade recommendation to look like this:

	/devel/v4l/docs/sphinx_1.7.9/bin/python3 -m venv sphinx_2.4.4
	. sphinx_2.4.4/bin/activate
	pip install -r ./Documentation/sphinx/requirements.txt

With is wrong (and it may not work). So, when recomending
an upgrade, exclude the venv dir from the search path, and
get the system's python.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/aa622ff71bebf6960fc0262fb90e7ebc7a999a02.1587478901.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-28 12:52:02 -06:00
Mauro Carvalho Chehab 2834a7412b scripts: sphinx-pre-install: change recommendation text if venv exists
If one is running a Sphinx version older than what's recommended,
but there's already a newer working virtual env, change the
text, as it is just a matter of switching to the new venv, instead
of creating a new one from scratch.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/bcf79d0399a1c3444ca938dcdce599c3273980ab.1587478901.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-28 12:52:02 -06:00
Mauro Carvalho Chehab 1ef70ced55 scripts: sphinx-pre-install: change the warning for version < 2.4.4
As requested by Jon, change the version check, in order to not
emit a warning if version is >= 1.7.9, but below 2.4.4.

After this patch, if someone used an older version, it will
say:

	./scripts/sphinx-pre-install
	Sphinx version 1.7.9
	Note: It is recommended at least Sphinx version 2.4.4 if you need PDF support.
	Detected OS: Fedora release 31 (Thirty One).

	To upgrade Sphinx, use:

		/devel/v4l/docs/sphinx_1.7.9/bin/python3 -m venv sphinx_2.4.4
		. sphinx_2.4.4/bin/activate
		pip install -r ./Documentation/sphinx/requirements.txt

	If you want to exit the virtualenv, you can use:
		deactivate

	All optional dependencies are met.
	Needed package dependencies are met.

If Sphinx is not detected at all, it

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/79584d317ba16f5d4f37801c5ee57cf04085f962.1587478901.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-28 12:52:02 -06:00
Mauro Carvalho Chehab a8b380c379 scripts: sphinx-pre-install: only ask to activate valid venvs
If a venv doesn't contain Sphinx, or has an older Sphinx
version, ignore it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/d11a00d88514e8a0357e1b0a05ebd518952a1d39.1587478901.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-28 12:52:02 -06:00
Mauro Carvalho Chehab 2f9c502552 scripts: sphinx-pre-install: add support for python -m venv
Since python 3.3, the recommended way to setup a virtual env is
via "python -m venv".

Set this as a default, if python version is compatible with
such feature.

While here, add more comments to it, as the script is
getting more complex. So, better to add more things, to avoid
accidentally breaking it while improving it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/252cc849c79527ad496247e4c481961478adf41c.1586883286.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-20 15:19:13 -06:00
Mauro Carvalho Chehab d6ebf1890c scripts: sphinx-pre-install: add support for OpenMandriva
It seems that Mageia and OpenMandriva will reunite on a single
distribution. In any case, both came from Mandriva. So, it is
close enough to use the same logic.

So, add support for it.

Tested with OpenMandriva 4.1 and with Mageia 7.1.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/692809729c6818a0b0f75513da15970c53d5565c.1586883286.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-20 15:19:13 -06:00
Mauro Carvalho Chehab e45a631742 scripts: sphinx-pre-install: address some issues with Gentoo
There are some small misdetections with Gentoo. While they
don't cause too much trouble, it keeps recomending to
install things that are already there.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/7f631edce102b02ccbdbfb18be1376a86b41373d.1586883286.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-20 15:19:13 -06:00
Mauro Carvalho Chehab bfc7f42810 scripts: sphinx-pre-install: fix a dependency hint with Ubuntu 16.04
Avoid the scripts to keep asking to install fonts-noto-cjk
on Ubuntu 16.04.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/912b664a8ca54e8c5c5767c3fe9171973eeddd6b.1586883286.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-20 15:19:12 -06:00
Mauro Carvalho Chehab b3df6223bd scripts: sphinx-pre-install: improve openSuse Tumbleweed check
Currently, with openSUSE Tumbleweed 20200303, it keeps
recommending this forever:

	sudo zypper install --no-recommends rsvg-view

This dependency will never be fulfilled there, as the package
now is named as on other distros: rsvg-convert.

So, improve the detection to avoid such issue.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/c3774f72ac36c5e5b5f446ae5db5b795d1f274f4.1586883286.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-20 15:19:12 -06:00
Mauro Carvalho Chehab d14d0c1aea scripts: sphinx-pre-install: improve distro detection check
The Arch-linux detection is hit by catting /etc/issue, whose
contents is (nowadays):

	Arch Linux \r (\l)

It sounds a little ackward to print such string, so,
instead, let's use the /etc/os-release file, with exists
on lots of distributions and should provide a more reliable
result.

We'll keep the old tests before it, in order to avoid possible
regressions with the other distros, although the new way should
probably work on all the currently supported distributions.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/472924557afdf2b5492ae2a48c5ecfae216d54e2.1586883286.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-20 15:19:12 -06:00
Tim Bird c428cd5228 scripts/sphinx-pre-install: add '-p python3' to virtualenv
With Ubuntu 16.04 (and presumably Debian distros of the same age),
the instructions for setting up a python virtual environment should
do so with the python 3 interpreter.  On these older distros, the
default python (and virtualenv command) might be python2 based.

Some of the packages that sphinx relies on are now only available
for python3.  If you don't specify the python3 interpreter for
the virtualenv, you get errors when doing the pip installs for
various packages

Fix this by adding '-p python3' to the virtualenv recommendation
line.

Signed-off-by: Tim Bird <tim.bird@sony.com>
Link: https://lore.kernel.org/r/1582594481-23221-1-git-send-email-tim.bird@sony.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-03-02 13:08:11 -07:00
Stephen Kitt d1c9038ab5 Allow git builds of Sphinx
When using a non-release version of Sphinx, from a local build (with
improvements for kernel doc handling, why not),

	sphinx-build --version

reports versions of the form

	sphinx-build 3.0.0+/4703d9119972

i.e. base version, a plus symbol, slash, and the start of the git hash
of whatever repository the command is run in (no, not the hash that
was used to build Sphinx!).

This patch fixes the installation check in sphinx-pre-install to
recognise such version output.

Signed-off-by: Stephen Kitt <steve@sk2.org>
Link: https://lore.kernel.org/r/20200124183316.1719218-1-steve@sk2.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-02-05 10:33:44 -07:00
Louis Taylor 0d0da9aa03 scripts/sphinx-pre-install: fix Arch latexmk dependency
On Arch Linux, latexmk is installed in the texlive-core package.

Signed-off-by: Louis Taylor <louis@kragniz.eu>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-11-07 13:17:24 -07:00
Jeremy MAURO 9692f2fdb1 scripts/sphinx-pre-install: Add a new path for the debian package "fonts-noto-cjk"
The latest debian version "bullseye/sid" has changed the path of the file
"notoserifcjk-regular.ttc", with the previous change and this change we
keep the backward compatibility and add the latest debian version

Signed-off-by: Jeremy MAURO <j.mauro@criteo.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-03 10:49:08 -06:00
Jeremy MAURO ff8fdb36ac scripts/sphinx-pre-install: allow checking for multiple missing files
The current implementation take a simple file as first argument, this
change allows to take a list as a first argument.

Some file could have a different path according distribution version

Signed-off-by: Jeremy MAURO <j.mauro@criteo.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-03 10:48:41 -06:00
Shuah Khan 2730ce017f scripts/sphinx-pre-install: add how to exit virtualenv usage message
Add usage message on how to exit the virtualenv after documentation
work is done.

Signed-off-by: Shuah Khan <skhan@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-01 06:54:14 -06:00
Mauro Carvalho Chehab 27eed923f7 scripts/sphinx-pre-install: seek for Noto CJK fonts for pdf output
The translations guide need Noto CJK fonts. So, add a logic that
would suggest its install for distros.

It also fix a few other issues while testing the script
with several distributions.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17 06:57:52 -03:00
Mauro Carvalho Chehab 4ea96d57bb scripts/sphinx-pre-install: cleanup Gentoo checks
On Gentoo, the portage changes for ImageMagick to work are
always suggested, even if already applied. While the two
extra commands should be harmless, add a check to avoid
reporting it without need.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17 06:57:52 -03:00
Mauro Carvalho Chehab 353290a9eb scripts/sphinx-pre-install: fix latexmk dependencies
The name of the package with carries latexmk is different
on two distros:

- On OpenSUSE, latexmk is packaged as "texlive-latexmk-bin"
- On Mageia, latexmk is packaged at "texlive-collection-basic"

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17 06:57:52 -03:00
Mauro Carvalho Chehab 56e5a63392 scripts/sphinx-pre-install: don't use LaTeX with CentOS 7
There aren't enough texlive packages for LaTeX-based builds
to work on CentOS/RHEL <= 7.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17 06:57:52 -03:00
Mauro Carvalho Chehab b308467c91 scripts/sphinx-pre-install: fix script for RHEL/CentOS
There's a missing parenthesis at the script, with causes it to
fail to detect non-Fedora releases (e. g. RHEL/CentOS).

Tested with Centos 7.6.1810.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17 06:57:52 -03:00
Mike Rapoport 8c69b77a01 scripts/sphinx-pre-install: fix out-of-tree build
Build of htmldocs fails for out-of-tree builds:

$ make V=1 O=~/build/kernel/ htmldocs
make -C /home/rppt/build/kernel -f /home/rppt/git/linux-docs/Makefile htmldocs
make[1]: Entering directory '/home/rppt/build/kernel'
make -f /home/rppt/git/linux-docs/scripts/Makefile.build obj=scripts/basic
rm -f .tmp_quiet_recordmcount
make -f /home/rppt/git/linux-docs/scripts/Makefile.build obj=Documentation htmldocs
Can't open Documentation/conf.py at /home/rppt/git/linux-docs/scripts/sphinx-pre-install line 230.
/home/rppt/git/linux-docs/Documentation/Makefile:80: recipe for target 'htmldocs' failed
make[2]: *** [htmldocs] Error 2

The scripts/sphinx-pre-install is trying to open files in the current
directory which is $KBUILD_OUTPUT rather than in $srctree.

Fix it.

Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-06-26 16:08:21 -06:00
Jonathan Corbet 8afecfb0ec Linux 5.2-rc4
-----BEGIN PGP SIGNATURE-----
 
 iQFSBAABCAA8FiEEq68RxlopcLEwq+PEeb4+QwBBGIYFAlz8fAYeHHRvcnZhbGRz
 QGxpbnV4LWZvdW5kYXRpb24ub3JnAAoJEHm+PkMAQRiG1asH/3ySguxqtqL1MCBa
 4/SZ37PHeWKMerfX6ZyJdgEqK3B+PWlmuLiOMNK5h2bPLzeQQQAmHU/mfKmpXqgB
 dHwUbG9yNnyUtTfsfRqAnCA6vpuw9Yb1oIzTCVQrgJLSWD0j7scBBvmzYqguOkto
 ThwigLUq3AILr8EfR4rh+GM+5Dn9OTEFAxwil9fPHQo7QoczwZxpURhScT6Co9TB
 DqLA3fvXbBvLs/CZy/S5vKM9hKzC+p39ApFTURvFPrelUVnythAM0dPDJg3pIn5u
 g+/+gDxDFa+7ANxvxO2ng1sJPDqJMeY/xmjJYlYyLpA33B7zLNk2vDHhAP06VTtr
 XCMhQ9s=
 =cb80
 -----END PGP SIGNATURE-----

Merge tag 'v5.2-rc4' into mauro

We need to pick up post-rc1 changes to various document files so they don't
get lost in Mauro's massive RST conversion push.
2019-06-14 14:18:53 -06:00
Bjorn Helgaas 54002b56b0 scripts/sphinx-pre-install: fix "dependenties" typo
Fix typo ("dependenties" for "dependencies").

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-06-07 11:35:36 -06:00
Linus Torvalds 2f4c533499 SPDX update for 5.2-rc3, round 1
Here is another set of reviewed patches that adds SPDX tags to different
 kernel files, based on a set of rules that are being used to parse the
 comments to try to determine that the license of the file is
 "GPL-2.0-or-later" or "GPL-2.0-only".  Only the "obvious" versions of
 these matches are included here, a number of "non-obvious" variants of
 text have been found but those have been postponed for later review and
 analysis.
 
 There is also a patch in here to add the proper SPDX header to a bunch
 of Kbuild files that we have missed in the past due to new files being
 added and forgetting that Kbuild uses two different file names for
 Makefiles.  This issue was reported by the Kbuild maintainer.
 
 These patches have been out for review on the linux-spdx@vger mailing
 list, and while they were created by automatic tools, they were
 hand-verified by a bunch of different people, all whom names are on the
 patches are reviewers.
 
 Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
 -----BEGIN PGP SIGNATURE-----
 
 iG0EABECAC0WIQT0tgzFv3jCIUoxPcsxR9QN2y37KQUCXPCHLg8cZ3JlZ0Brcm9h
 aC5jb20ACgkQMUfUDdst+ykxyACgql6ktH+Tv8Ho1747kKPiFca1Jq0AoK5HORXI
 yB0DSTXYNjMtH41ypnsZ
 =x2f8
 -----END PGP SIGNATURE-----

Merge tag 'spdx-5.2-rc3-1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core

Pull yet more SPDX updates from Greg KH:
 "Here is another set of reviewed patches that adds SPDX tags to
  different kernel files, based on a set of rules that are being used to
  parse the comments to try to determine that the license of the file is
  "GPL-2.0-or-later" or "GPL-2.0-only". Only the "obvious" versions of
  these matches are included here, a number of "non-obvious" variants of
  text have been found but those have been postponed for later review
  and analysis.

  There is also a patch in here to add the proper SPDX header to a bunch
  of Kbuild files that we have missed in the past due to new files being
  added and forgetting that Kbuild uses two different file names for
  Makefiles. This issue was reported by the Kbuild maintainer.

  These patches have been out for review on the linux-spdx@vger mailing
  list, and while they were created by automatic tools, they were
  hand-verified by a bunch of different people, all whom names are on
  the patches are reviewers"

* tag 'spdx-5.2-rc3-1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core: (82 commits)
  treewide: Add SPDX license identifier - Kbuild
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 225
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 224
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 223
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 222
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 221
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 220
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 218
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 217
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 216
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 215
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 214
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 213
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 211
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 210
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 209
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 207
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 206
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 203
  treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 201
  ...
2019-05-31 08:34:32 -07:00
Thomas Gleixner c942fddf87 treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 157
Based on 3 normalized pattern(s):

  this program is free software you can redistribute it and or modify
  it under the terms of the gnu general public license as published by
  the free software foundation either version 2 of the license or at
  your option any later version this program is distributed in the
  hope that it will be useful but without any warranty without even
  the implied warranty of merchantability or fitness for a particular
  purpose see the gnu general public license for more details

  this program is free software you can redistribute it and or modify
  it under the terms of the gnu general public license as published by
  the free software foundation either version 2 of the license or at
  your option any later version [author] [kishon] [vijay] [abraham]
  [i] [kishon]@[ti] [com] this program is distributed in the hope that
  it will be useful but without any warranty without even the implied
  warranty of merchantability or fitness for a particular purpose see
  the gnu general public license for more details

  this program is free software you can redistribute it and or modify
  it under the terms of the gnu general public license as published by
  the free software foundation either version 2 of the license or at
  your option any later version [author] [graeme] [gregory]
  [gg]@[slimlogic] [co] [uk] [author] [kishon] [vijay] [abraham] [i]
  [kishon]@[ti] [com] [based] [on] [twl6030]_[usb] [c] [author] [hema]
  [hk] [hemahk]@[ti] [com] this program is distributed in the hope
  that it will be useful but without any warranty without even the
  implied warranty of merchantability or fitness for a particular
  purpose see the gnu general public license for more details

extracted by the scancode license scanner the SPDX license identifier

  GPL-2.0-or-later

has been chosen to replace the boilerplate/reference in 1105 file(s).

Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Allison Randal <allison@lohutok.net>
Reviewed-by: Richard Fontana <rfontana@redhat.com>
Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Cc: linux-spdx@vger.kernel.org
Link: https://lkml.kernel.org/r/20190527070033.202006027@linutronix.de
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2019-05-30 11:26:37 -07:00
Mauro Carvalho Chehab 9b88ad5464 scripts/sphinx-pre-install: always check if version is compatible with build
Call the script every time a make docs target is selected, on
a simplified check mode.

With this change, the script will set two vars:

$min_version - obtained from `needs_sphinx` var inside
	       conf.py (currently, '1.3')

$rec_version - obtained from sphinx/requirements.txt.

With those changes, a target like "make htmldocs" will do:

1) If no sphinx-build/sphinx-build3 is found, it will run
   the script on normal mode as before, checking for all
   system dependencies and providing install hints for the
   needed programs and will abort the build;

2) If no sphinx-build/sphinx-build3 is found, but there is
   a sphinx_${VER}/bin/activate file, and if
   ${VER} >= $min_version (string comparation), it will
   run in full mode, and will recommend to activate the
   virtualenv. If there are multiple virtualenvs, it
   will string sort the versions, recommending the
   highest version and will abort the build;

3) If Sphinx is detected but has a version lower than
   $min_version, it will run in full mode - with will
   recommend creating a virtual env using sphinx/requirements.txt,
   and will abort the build.

4) If Sphinx is detected and version is lower than
   $rec_version, it will run in full mode and will
   recommend creating a virtual env using sphinx/requirements.txt.

   In this case, it **won't** abort the build.

5) If Sphinx is detected and version is equal or righer than
   $rec_version it will return just after detecting the
   version ("quick mode"), not checking if are there any
   missing dependencies.

Just like before, if one wants to install Sphinx from the
distro, it has to call the script manually and use `--no-virtualenv`
argument to get the hints for his OS:

    You should run:

	sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme

While here, add a small help for the three optional arguments
for the script.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-30 10:40:24 -06:00
Mauro Carvalho Chehab c4c562defe scripts/sphinx-pre-install: get rid of RHEL7 explicity check
RHEL8 was already launched. This test won't get it, and will
do the wrong thing. Ok, we could fix it, but now we check
Sphinx version to ensure that it matches the minimal (1.3),
so there's no need for an explicit check there.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-30 10:40:23 -06:00
Mauro Carvalho Chehab 44f4216517 scripts/sphinx-pre-install: make activate hint smarter
It is possible that multiple Sphinx virtualenvs are installed
on a given kernel tree. Change the logic to get the latest
version of those, as this is probably what the user wants.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-30 10:40:23 -06:00
Mauro Carvalho Chehab 77d09ad9dc scripts/sphinx-pre-install: make it handle Sphinx versions
As we want to switch to a newer Sphinx version in the future,
add some version detected logic, checking if the current
version meets the requirement and suggesting upgrade it the
version is supported but too old.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-24 09:09:32 -06:00
Mauro Carvalho Chehab 5f6df00fd4 docs: scripts/sphinx-pre-install: suggest latexmk for building pdf
The usage of latexmk improves the PDF output, as it re-run
xelatex when it detects the need, in order to properly generate
indexes and cross-references.

As this is not a mandatory requirement, only suggest its
addition.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-04-01 14:33:48 -06:00
Mauro Carvalho Chehab 54d6d73f50 docs-rst: don't require adjustbox anymore
Only the media PDF book was requiring adjustbox, in order to
scale big tables. That worked pretty good with Sphinx versions
1.4 and 1.5, but Spinx 1.6 changed the way tables are produced,
by introducing some weird macros before tabulary.
That causes adjustbox to fail. So, it can't be used anymore,
and its usage was removed from the media book.

So, let's remove it from conf.py and sphinx-pre-install.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-09-08 10:02:55 -06:00
Mauro Carvalho Chehab 9b756a9d07 scripts/sphinx-pre-install: add minimum support for RHEL
RHEL 7.x and clone distros are shipped with Sphinx 1.1.x,
with is incompatible with Kernel ReST markups.

So, on those systems, the only alternative is to install
it via a Python virtual environment.

While seeking for "pip" on CentOS 7.3, I noticed that it
is not really needed, as python-virtualenv has its version
packaged there already. So, remove this from the list of
requirements for all distributions.

With regards to PDF, we need at least texlive-tabulary
extension, but that is not shipped there (at least on
CentOS). So, disable PDF packages as a whole.

Please notice, however, that texlive + amsmath is needed for
ReST to properly handle ReST ".. math::" tags. Yet, Sphinx
fall back to display the LaTeX math expressions as-is, if
such extension is not available.

So, let's just disable all texlive packages as a whole.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-07 14:26:41 -06:00
Mauro Carvalho Chehab 800d408a34 sphinx-pre-install: add support for Mageia
Add support for detecting and installing missing packages
on Mageia. I opted to use "urpmi" at the install instructions,
as this is present on Mageia since ever. Yet, if I were using
Mageia 6, I would likely be using "dnf", as it is, IMHO,
easier to use.

Tested with Mageia 6.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-23 16:00:04 -06:00
Mauro Carvalho Chehab bba1e4cbdb sphinx-pre-install: fix USE needs for GraphViz and ImageMagick
Gentoo need some USE for GraphViz and ImageMagick to have
the features required by kfigure.py.

Output that when providing instructions for Gentoo.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-23 15:51:40 -06:00
Mauro Carvalho Chehab 8e7d5d15e7 sphinx-pre-install: add dependencies for ImageMagick to work with svg
ImageMagick actually uses librsvg for conversions when converiting
from SVG (actually, it uses rsvg-convert). That causes the build to
fail with:

	WARNING: Error #1 when calling: /usr/bin/convert /home/mchehab/docs/Documentation/media/uapi/v4l/selection.svg /home/mchehab/docs/Documentation/output/latex/selection.pdf
	convert: delegate failed `'rsvg-convert' -o '%o' '%i'' @ error/delegate.c/InvokeDelegate/1919.
	convert: unable to open file `/tmp/magick-8883oOQfHzrA5trM': No such file or directory @ error/constitute.c/ReadImage/544.

Add the corresponding dependencies.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-23 15:51:35 -06:00
Mauro Carvalho Chehab 5d88953c32 sphinx-pre-install: check for the need of graphviz-gd
On newer versions of graphviz packaging on Fedora, it is needed to
install a separate package for PDF support.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-23 15:51:30 -06:00
Mauro Carvalho Chehab fb947f3f47 sphinx-pre-install: use a requirements file
Instead of using 3 commands to install a virtualenv, use
a single one, reading the requirements from this file:

	Documentation/sphinx/requirements.txt

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-23 15:51:24 -06:00
Mauro Carvalho Chehab 5be33182d4 sphinx-pre-install: detect an existing virtualenv
Detect if the script runs after creating the virtualenv,
printing the command line commands to enable the virtualenv.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-23 15:51:10 -06:00
Mauro Carvalho Chehab 24071ac1a6 scripts/sphinx-pre-install: add a script to check Sphinx install
Solving Sphinx dependencies can be painful. Add a script to
check if everything is ok.

Tested on:
	- Fedora 25 and 26;
	- Ubuntu 17.04;
	- OpenSuse Tumbleweed;
	- Arch Linux;
	- Gentoo.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-23 15:50:58 -06:00