Commit Graph

103 Commits

Author SHA1 Message Date
Akira Yokosawa aa872e0647 docs: pdfdocs: Adjust \headheight for fancyhdr
Fancyhdr prior to v4.0 outputs a message per document as follows:

    Package Fancyhdr Warning: \headheight is too small (12.0pt):
    Make it at least 13.59999pt.
    We now make it that large for the rest of the document.
    This may cause the page layout to be inconsistent, however.

Fancyhdr v4.0 complains (once a page!) as follows:

    Package fancyhdr Warning: \headheight is too small (12.0pt):
    (fancyhdr)    Make it at least 13.59999pt, for example:
    (fancyhdr)    \setlength{\headheight}{13.59999pt}.
    (fancyhdr)    You might also make \topmargin smaller to compensate:

    (fancyhdr)    \addtolength{\topmargin}{-1.59999pt}.

Related item in fancyhdr v4.0 announcement on 2021-01-04 [1]:

    Backward incompatible changes:
      - Eliminate adjustments of \headheight or \footskip, when the
        header or footer is too high.

[1]: https://www.ctan.org/ctan-ann/id/mailman.2685.1609863692.2532.ctan-ann@ctan.org

Silence the warnings by adding a couple of \addtolength commands in
the preamble.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/c5a5577e-5de8-9cd4-9253-956ccc748417@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-10-12 14:09:03 -06:00
Akira Yokosawa 7c5c18bdb6 docs: pdfdocs: Fix typo in CJK-language specific font settings
There were typos in the fallback definitions of dummy LaTeX macros
for systems without CJK fonts.
They cause build errors in "make pdfdocs" on such systems.
Fix them.

Fixes: e291ff6f5a ("docs: pdfdocs: Add CJK-language-specific font settings")
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/ad7615a5-f8fa-2bc3-de6b-7ed49d458964@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-09-06 16:53:39 -06:00
Akira Yokosawa 29ac982235 docs: pdfdocs: Teach xeCJK about character classes of quotation marks
Quotation marks in "KR" and "JP" variants of Noto CJK fonts are half
width.
xeCJK assumes they are full width by default and does excessive kerning
around them in Korean and Japanese translations.

Give xeCJK proper hints by the \xeCJKDeclareCharClass command.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/0da9e3c5-2716-f576-1df5-2f28ea69f0e8@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:33 -06:00
Akira Yokosawa 788d28a257 docs: pdfdocs: Permit AutoFakeSlant for CJK fonts
Noto CJK fonts don't provide italic shapes.
The AutoFakeSlant option of fontspec and xeCJK packages can be used as
a workaround.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/502335cc-9a95-3c2a-7744-6cc56ecaf628@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:33 -06:00
Akira Yokosawa 77abc2c230 docs: pdfdocs: One-half spacing for CJK translations
CJK documents are much easier to read with a wider baseline stretch.
Applying onehalfspacing option of "setspace" package looks reasonable.

Note: \usepackage{setspace} needs to be before that of hyperref in the
preamble.
The 'extrapackages' key (available since Sphinx 2.3) is for this purpose.
For systems with Sphinx < 2.3, dummy commands of \onehalfspacing and
\singlespacing are provided instead.
One-half spacing is not effective in LaTeX sources generated by such
revisions of Sphinx.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/547a1f1c-0bb5-20a7-ea0e-951bfc3c3925@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:32 -06:00
Akira Yokosawa 35382965bd docs: pdfdocs: Preserve inter-phrase space in Korean translations
In Korean typesetting, inter-phrase spaces in Hangul text have
a similar role as the the inter-word spaces in Latin text.
They can be preserved by the \xeCJKsetup{CJKspace=true} option.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/68de2e52-e6d1-3f01-c097-15ba7b28a319@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:32 -06:00
Akira Yokosawa 7eb368cc31 docs: pdfdocs: Choose Serif font as CJK mainfont if possible
"Noto Serif CJK SC" and its variants suit better with the roman font
of Latin letters.

On some distros such as Fedora, it is possible to partially install
"Noto Sans CJK" fonts.
So, if the Serif fonts are not found on the system, fall back to the
Sans fonts.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/5e454140-5d0c-35d4-8c31-3ffb2420793a@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:32 -06:00
Akira Yokosawa e291ff6f5a docs: pdfdocs: Add CJK-language-specific font settings
zh_TW, ko_KR, and ja_JP translations have their preferred glyph sets
different from that of zh_CN.

To switch CJK font in the middle of the translations, introduce custom
LaTeX macros listed below:

    \kerneldocBeginSC
    \kerneldocEndSC
    \kerneldocBeginTC
    \kerneldocEndTC
    \kerneldocBeginKR
    \kerneldocEndKR
    \kerneldocBeginJP
    \kerneldocEndJP

, and embed a pair of macros in each language's index.rst.

NOTE 1: Update of zh_TW/index.rst is deferred to a follow-up change.

NOTE 2: Custom macros added here do not imply \kerneldocCJK(on|off).
This is intentional.  For example, \kerneldocCJKoff needs to be
at the top of Italian translations' index.rst for the footer of
final zh_TW page to be properly typeset.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/31906baf-7490-68cd-7153-4e4d320fb9b0@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:32 -06:00
Akira Yokosawa 659653c9e5 docs: pdfdocs: Refactor config for CJK document
To make generated LaTeX code portable across systems with different sets
of available fonts, convert font-availability check in python code to
LaTeX code by using a conditional command provided by the "fontspec"
package.

This will help those who run Sphinx on one machine/container and run
latexmk on other machines/containers.

Remove import of check_output as it is unused any more.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/4baf88af-316d-8aee-240f-6ccbc20907d7@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:32 -06:00
Jonathan Corbet 102caec107 docs: Take a little noise out of the build process
Sphinx 3.0 works at this point (albeit slowly) so stop scaring people
with a loud warning.  We also don't need to babble about CJK support in the
LaTeX build.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-06-17 13:49:18 -06:00
Akira Yokosawa 0afd4df0d1 docs: pdfdocs: Prevent column squeezing by tabulary
Setting a reasonable width to \tymin prevents column squeezing
by tabulary.
Width of 20em works well in almost all the tables still in the
ascii-art format.

Excerpt from tabulary package documentation at [1]:

    To stop very narrow columns being too 'squeezed' by this process
    any columns that are narrower than \tymin are set to their natural
    width.

[1]: https://mirrors.ctan.org/macros/latex/contrib/tabulary/tabulary.pdf

Note: Sphinx has its own default value of \tymin set in
sphinxlatextables.sty (Sphinx 4.0.2) and sphinxmulticell.sty
(Sphinx 2.4.4) as follows:

    \setlength{\tymin}{3\fontcharwd\font`0 }

, which is not sufficient for kernel-doc.

Tested against Sphinx versions 2.4.4 and 4.0.2.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/277d68fa-c96a-0ccb-6ce0-4d314851d9fe@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-06-01 16:49:52 -06:00
Akira Yokosawa f7ebe6b769 docs: Activate exCJK only in CJK chapters
Activating xeCJK in English and Italian-translation documents
results in sub-optimal typesetting with wide-looking apostrophes
and quotation marks.

The xeCJK package provides macros for enabling and disabling its
effect in the middle of a document, namely \makexeCJKactive and
\makexeCJKinactive.

So the goal of this change is to activate xeCJK in the relevant
chapters in translations.

To do this:

    o Define custom macros in the preamble depending on the
      availability of the "Noto Sans CJK" font so that those
      macros can be used regardless of the use of xeCJK package.

    o Patch \sphinxtableofcontents so that xeCJK is inactivated
      after table of contents.

    o Embed those custom macros in each language's index.rst file
      as a ".. raw:: latex" construct.

Note: A CJK chapter needs \kerneldocCJKon in front of its chapter
heading, while a non-CJK chapter should have \kerneldocCJKoff
below its chapter heading.

This is to make sure the CJK font is available to CJK chapter's
heading and ending page's footer.

Tested against Sphinx versions 2.4.4 and 4.0.2.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Tested-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/lkml/2061da0a-6ab1-35f3-99c1-dbc415444f37@gmail.com
Link: https://lore.kernel.org/r/83208ddc-5de9-b283-3fd6-92c635348ca0@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-05-27 09:59:41 -06:00
Mauro Carvalho Chehab 3b4c963243 docs: conf.py: adjust the LaTeX document output
Changeset f546ff0c0c ("Move our minimum Sphinx version to 1.7")
cleaned up some compatibility issues with previous Sphinx
versions, but it also dropped the PDF margin sets.

Without that, the media documentation won't build fine, as
the margins are too wide to display texts with monospaced
fonts.

While here, align the  "latex_elements = {" values, and add
a few other sphinxsetup configs in order to allow Sphinx to
wrap long lines on literal blocks.

Fixes: f546ff0c0c ("Move our minimum Sphinx version to 1.7")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

 Documentation/conf.py | 31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)
Link: https://lore.kernel.org/r/911fbac185dd09c7df715cf4153361b81f04b7ad.1614787053.git.mchehab+huawei@kernel.org

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-03-08 17:20:03 -07:00
Matthew Wilcox 36d8900d20 Fix unaesthetic indentation
The current documentation build looks like this:

$ make htmldocs
  SPHINX  htmldocs --> file:///home/willy/kernel/linux-next/Documentation/output
make[2]: Nothing to be done for 'html'.
WARNING: The kernel documentation build process
        support for Sphinx v3.0 and above is brand new. Be prepared for
        possible issues in the generated output.
        $

That extra indentation before my next prompt isn't pretty.  This patch
fixes it, but I'm not a pythonista, and maybe there's a better way.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
Link: https://lore.kernel.org/r/20210215161757.GD2858050@casper.infradead.org
[jc: tweaked for the "better way"]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-02-22 14:35:04 -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
Jonathan Corbet 13fef8ef9f docs: Note that sphinx 1.7 will be required soon
The time has come to drop support for some truly ancient versions of
sphinx; put in a warning now.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-12-11 13:53:38 -07:00
Mauro Carvalho Chehab 63fdc4625a docs: admin-guide: add a features list
Add a feature list matrix at the admin-guide.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/f6c1e366fbc7ce1c9c94c7dc6c7852c6377cc0be.1606748711.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-12-03 15:10:15 -07:00
Linus Torvalds e6b0bd61a7 This pull contains a series of warning fixes from Mauro; once applied, the
number of warnings from the once-noisy docs build process is nearly zero.
 Getting to this point has required a lot of work; once there, hopefully we
 can keep things that way.
 
 I have packaged this as a separate pull because it does a fair amount of
 reaching outside of Documentation/.  The changes are all in comments and in
 code placement.  It's all been in linux-next since last week.
 -----BEGIN PGP SIGNATURE-----
 
 iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAl+hscQPHGNvcmJldEBs
 d24ubmV0AAoJEBdDWhNsDH5YgZAH/0JeDA/1VLZYYTmdABz8mjBZsoW9tyPGGztF
 nsh5ykdHhL3MeTRwumW5armLVrfKhd1XT+nIzD7OcWlqu+RDOvQ5I95rahr473hP
 1SHTjqm3/AlJwQoeS72X5U6QEJQ58e2IwCbP23H3x7I3Q3snEA/HhswzxurfoB/Z
 j81YzDV2YPEc0LJWZ5Vn0NEdwP8cdpFv5rojsQmepq7K0yJ7tEHb7/u2cEuUBgXS
 8LcYCNPLpiN+q5N8uQ5oDjIUNdLQvP03kgKtQWiCTr4BRydOrDlJie28LIedamEz
 anu7UfaVK4bxn+ugRI0g2+aWQKux81ULCinKUWmLRNbcxjhaQqQ=
 =hDfp
 -----END PGP SIGNATURE-----

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

Pull documentation build warning fixes from Jonathan Corbet:
 "This contains a series of warning fixes from Mauro; once applied, the
  number of warnings from the once-noisy docs build process is nearly
  zero.

  Getting to this point has required a lot of work; once there,
  hopefully we can keep things that way.

  I have packaged this as a separate pull because it does a fair amount
  of reaching outside of Documentation/. The changes are all in comments
  and in code placement. It's all been in linux-next since last week"

* tag 'docs-5.10-warnings' of git://git.lwn.net/linux: (24 commits)
  docs: SafeSetID: fix a warning
  amdgpu: fix a few kernel-doc markup issues
  selftests: kselftest_harness.h: fix kernel-doc markups
  drm: amdgpu_dm: fix a typo
  gpu: docs: amdgpu.rst: get rid of wrong kernel-doc markups
  drm: amdgpu: kernel-doc: update some adev parameters
  docs: fs: api-summary.rst: get rid of kernel-doc include
  IB/srpt: docs: add a description for cq_size member
  locking/refcount: move kernel-doc markups to the proper place
  docs: lockdep-design: fix some warning issues
  MAINTAINERS: fix broken doc refs due to yaml conversion
  ice: docs fix a devlink info that broke a table
  crypto: sun8x-ce*: update entries to its documentation
  net: phy: remove kernel-doc duplication
  mm: pagemap.h: fix two kernel-doc markups
  blk-mq: docs: add kernel-doc description for a new struct member
  docs: userspace-api: add iommu.rst to the index file
  docs: hwmon: mp2975.rst: address some html build warnings
  docs: net: statistics.rst: remove a duplicated kernel-doc
  docs: kasan.rst: add two missing blank lines
  ...
2020-11-03 13:14:14 -08:00
Mauro Carvalho Chehab a7ee04b3ef docs: add ABI documentation to the admin-guide book
As we don't want a generic Sphinx extension to execute commands,
change the one proposed to Markus to call the abi_book.pl
script.

Use a script to parse the Documentation/ABI directory and output
it at the admin-guide.

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/5651482b06500e69a1acdf92152f90a203e6521d.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-10-30 13:07:01 +01:00
Mauro Carvalho Chehab d29f34c098 sphinx: conf.py: properly handle Sphinx 4.0
One of the checks for Sphinx 3+ is broken, causing some
C warnings to return back with Sphinx 4.0.x.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/d5abc30056dafeec0778a46263a45401bdc7f11e.1603791716.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-10-28 11:26:10 -06:00
Mauro Carvalho Chehab 14059a38a4 docs: conf.py: change the Sphinx 3.x+ text
After the build fix patches, it is believed that the output
with Sphinx 3.x won't be a problem. Still, the C domain
support was re-written, and this can have caused hidden
issues.

So, let's keep the warning, changing it to a lighter
warning text.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15 07:49:45 +02:00
Mauro Carvalho Chehab b34b86d7a4 docs: conf.py: fix c:function support with Sphinx 3.x
Sphinx C parser for the C domain is now more pedantic when
trying to identify the function types. That prevents scope
macros to be used as type defines.

Yet, since 3.0.2, it is possible to provide it a list of
such macros. Add them, in order to solve several Sphinx 3.x
warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15 07:49:45 +02:00
Jonathan Corbet afde706afd Make the docs build "work" with Sphinx 3.x
The Sphinx 3.x upgrade broke a number of things in our special "cdomain"
module that are not easy to fix.  For now, just disable that module for the
3.x build and put out a warning that the build will not be perfect.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-09-04 10:13:45 -06:00
Alexander A. Klimov 93431e0607 Replace HTTP links with HTTPS ones: documentation
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.

Deterministic algorithm:
For each file:
  For each line:
    If doesn't contain `\bxmlns\b`:
      For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
        If both the HTTP and HTTPS versions
        return 200 OK and serve the same content:
          Replace HTTP with HTTPS.

Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-06-08 09:30:19 -06:00
Mauro Carvalho Chehab 25813cae1e docs: LaTeX/PDF: drop list of documents
The building system can auto-generate a list of documents since
commit: 9d42afbe6b ("docs: pdf: add all Documentation/*/index.rst to PDF output").

The added logic there allows keeping the existing list, but
there's not real reason to keep it. Now, the media document
has gone (it was split into tree).

So, it sounds about time to get rid of the manual entries,
and let the script to generate it automatically instead.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/9345dba7164497dbf28578f6ec271e479379610c.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-20 15:35:58 -06:00
Mauro Carvalho Chehab 4658b0eb94 docs: conf.py: avoid thousands of duplicate label warning on Sphinx
The autosectionlabel extension is nice, as it allows to refer to
a section by its name without requiring any extra tag to create
a reference name.

However, on its default, it has two serious problems:

1) the namespace is global. So, two files with different
   "introduction" section would create a label with the
   same name. This is easily solvable by forcing the extension
   to prepend the file name with:

	autosectionlabel_prefix_document = True

2) It doesn't work hierarchically. So, if there are two level 1
   sessions (let's say, one labeled "open" and another one "ioctl")
   and both have a level 2 "synopsis" label, both section 2 will
   have the same identical name.

   Currently, there's no way to tell Sphinx to create an
   hierarchical reference like:

		open / synopsis
		ioctl / synopsis

  This causes around 800 warnings. So, the fix should be to
  not let autosectionlabel to produce references for anything
  that it is not at a chapter level within any doc, with:

	autosectionlabel_maxdepth = 2

Fixes: 58ad30cf91 ("docs: fix reference to core-api/namespaces.rst")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/74f4d8d91c648d7101c45b4b99cc93532f4dadc6.1584716446.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-03-20 17:01:34 -06:00
Jonathan Corbet 58ad30cf91 docs: fix reference to core-api/namespaces.rst
Fix a couple of dangling links to core-api/namespaces.rst by turning them
into proper references.  Enable the autosection extension (available since
Sphinx 1.4) to make this work.

Co-developed-by: Federico Vaga <federico.vaga@vaga.pv.it>
Fixes: fcfacb9f83 ("doc: move namespaces.rst from kbuild/ to core-api/")
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-03-19 12:52:01 -06:00
Kees Cook aa20485528 doc-rst: Programmatically render MAINTAINERS into ReST
In order to have the MAINTAINERS file visible in the rendered ReST
output, this makes some small changes to the existing MAINTAINERS file
to allow for better machine processing, and adds a new Sphinx directive
"maintainers-include" to perform the rendering.

Features include:
- Per-subsystem reference links: subsystem maintainer entries can be
  trivially linked to both internally and external. For example:
  https://www.kernel.org/doc/html/latest/process/maintainers.html#secure-computing

- Internally referenced .rst files are linked so they can be followed
  when browsing the resulting rendering. This allows, for example, the
  future addition of maintainer profiles to be automatically linked.

- Field name expansion: instead of the short fields (e.g. "M", "F",
  "K"), use the indicated inline "full names" for the fields (which are
  marked with "*"s in MAINTAINERS) so that a rendered subsystem entry
  is more human readable. Email lists are additionally comma-separated.
  For example:

    SECURE COMPUTING
	Mail:	  Kees Cook <keescook@chromium.org>
	Reviewer: Andy Lutomirski <luto@amacapital.net>,
		  Will Drewry <wad@chromium.org>
	SCM:	  git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git seccomp
	Status:	  Supported
	Files:	  kernel/seccomp.c include/uapi/linux/seccomp.h
		  include/linux/seccomp.h tools/testing/selftests/seccomp/*
		  tools/testing/selftests/kselftest_harness.h
		  userspace-api/seccomp_filter
	Content regex:	\bsecure_computing \bTIF_SECCOMP\b

Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-02 10:03:17 -06:00
Mauro Carvalho Chehab e0de2b59e2 docs: conf.py: only use CJK if the font is available
If we try to build a book with asian characters with XeLaTeX
and the font is not available, it will produce an error.

So, instead, add a logic at conf.py to detect if the proper
font is installed.

This will avoid an error while building the document, although
the result may not be readable.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17 06:57:51 -03:00
Mauro Carvalho Chehab 24889dad3d docs: conf.py: add CJK package needed by translations
In order to be able to output Asian symbols with XeLaTeX, we
need the xeCJK package, and a default font for CJK symbols.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17 06:57:51 -03:00
Mauro Carvalho Chehab 9d42afbe6b docs: pdf: add all Documentation/*/index.rst to PDF output
Currently, all index files should be manually added to the
latex_documents array at conf.py.

While this allows fine-tuning some LaTeX specific things, like
the name of the output file and the name of the document, it
is not uncommon to forget adding new documents there.

So, add a logic that will seek for all Documentation/*/index.rst.
If the index is not yet at latex_documents, it includes using
a reasonable default.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17 06:57:51 -03:00
Stephen Kitt 7282a93f4d Disable Sphinx SmartyPants in HTML output
The handling of dashes in particular results in confusing
documentation in a number of instances, since "--" becomes an
en-dash. This disables SmartyPants wholesale, losing smart quotes
along with smart dashes.

With Sphinx 1.6 we could fine-tune the conversion, using the new
smartquotes and smartquotes_action settings.

Signed-off-by: Stephen Kitt <steve@sk2.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-06-30 15:30:34 -06:00
Jonathan Corbet d74b0d31dd Docs: An initial automarkup extension for sphinx
Rather than fill our text files with :c:func:`function()` syntax, just do
the markup via a hook into the sphinx build process.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-06-26 11:14:09 -06:00
Jonathan Corbet 3bc8088464 docs: Fix conf.py for Sphinx 2.0
Our version check in Documentation/conf.py never envisioned a world where
Sphinx moved beyond 1.x.  Now that the unthinkable has happened, fix our
version check to handle higher version numbers correctly.

Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-24 09:09:32 -06:00
Linus Torvalds 01aa9d518e This is a fairly typical cycle for documentation. There's some welcome
readability improvements for the formatted output, some LICENSES updates
 including the addition of the ISC license, the removal of the unloved and
 unmaintained 00-INDEX files, the deprecated APIs document from Kees, more
 MM docs from Mike Rapoport, and the usual pile of typo fixes and
 corrections.
 -----BEGIN PGP SIGNATURE-----
 
 iQIcBAABAgAGBQJbztcuAAoJEI3ONVYwIuV6nTAP/0Be+5dNPGJmSnb/RbkwBuBV
 zAFVUj2sx4lZlRmWRZ0r7AOef2eSw3IvwBix/vnmllYCVahjp+BdRbhXQAijjyeb
 FWWjOH50/J+BaxSthAINiLRLvuoe0D/M08OpmXQfRl5q0S8RufeV3BDtEABx9j2n
 IICPGTl8LpPUgSMA4cw8zPhHdauhZpbmL2mGE9LXZ27SJT4S8lcHMwyPU1n5S+Jd
 ChEz5g9dYr3GNxFp712pkI5GcVL3tP2nfoVwK7EuGf1tvSnEnn2kzac8QgMqorIh
 xB2+Sh4XIUCbHYpGHpxIniD+WI4voNr/E7STQioJK5o2G4HTuxLjktvTezNF8paa
 hgNHWjPQBq0OOCdM/rsffONFF2J/v/r7E3B+kaRg8pE0uZWTFaDMs6MVaL2fL4Ls
 DrFhi90NJI/Fs7uB4sriiviShAhwboiSIRXJi4VlY/5oFJKHFgqes+R7miU+zTX3
 2qv0k4mWZXWDV9w1piPxSCZSdRzaoYSoxEihX+tnYpCyEcYd9ovW/X1Uhl/wCWPl
 Ft+Op6rkHXRXVfZzTLuF6PspZ4Udpw2PUcnA5zj5FRDDBsjSMFR31c19IFbCeiNY
 kbTIcqejJG1WbVrAK4LCcFyVSGxbrr281eth4rE06cYmmsz3kJy1DB6Lhyg/2vI0
 I8K9ZJ99n1RhPJIcburB
 =C0wt
 -----END PGP SIGNATURE-----

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

Pull documentation updates from Jonathan Corbet:
 "This is a fairly typical cycle for documentation. There's some welcome
  readability improvements for the formatted output, some LICENSES
  updates including the addition of the ISC license, the removal of the
  unloved and unmaintained 00-INDEX files, the deprecated APIs document
  from Kees, more MM docs from Mike Rapoport, and the usual pile of typo
  fixes and corrections"

* tag 'docs-4.20' of git://git.lwn.net/linux: (41 commits)
  docs: Fix typos in histogram.rst
  docs: Introduce deprecated APIs list
  kernel-doc: fix declaration type determination
  doc: fix a typo in adding-syscalls.rst
  docs/admin-guide: memory-hotplug: remove table of contents
  doc: printk-formats: Remove bogus kobject references for device nodes
  Documentation: preempt-locking: Use better example
  dm flakey: Document "error_writes" feature
  docs/completion.txt: Fix a couple of punctuation nits
  LICENSES: Add ISC license text
  LICENSES: Add note to CDDL-1.0 license that it should not be used
  docs/core-api: memory-hotplug: add some details about locking internals
  docs/core-api: rename memory-hotplug-notifier to memory-hotplug
  docs: improve readability for people with poorer eyesight
  yama: clarify ptrace_scope=2 in Yama documentation
  docs/vm: split memory hotplug notifier description to Documentation/core-api
  docs: move memory hotplug description into admin-guide/mm
  doc: Fix acronym "FEKEK" in ecryptfs
  docs: fix some broken documentation references
  iommu: Fix passthrough option documentation
  ...
2018-10-24 18:01:11 +01:00
Darrick J. Wong 44ba0bb4f2 docs: improve readability for people with poorer eyesight
My eyesight is not in good shape, which means that I have difficulty
reading the online Linux documentation.  Specifically, body text is
oddly small compared to list items and the contrast of various text
elements is too low for me to be able to see easily.

Therefore, alter the HTML theme overrides to make the text larger and
increase the contrast for better visibility, and trust the typeface
choices of the reader's browser.

For the PDF output, increase the text size, use a sans-serif typeface
for sans-serif text, and use a serif typeface for "roman" serif text.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Acked-by: Dave Chinner <dchinner@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-10-07 09:16:50 -06:00
Darrick J. Wong 8a98ec7c7b docs: promote the ext4 data structures book to top level
Move the ext4 data structures book to Documentation/filesystems/ext4/
since the administrative information moved elsewhere.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-10-05 19:20:08 -04:00
Darrick J. Wong d309121592 docs: move ext4 administrative docs to admin-guide/
Move the ext4 mount option and other administrative stuff to the Linux
administrator's guide.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-10-05 19:11:59 -04:00
Darrick J. Wong e5f0926115 docs: generate a separate ext4 pdf file from the documentation
The documentation build scripts won't build a pdf for the ext4
documentation unless explicitly called for, so ask for a separate
ext4.pdf to be generated with all the documentation.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-10-02 22:40:32 -04:00
Darrick J. Wong b4becd48b7 ext4: import inode data fork chapter from wiki page
Import the chapter about inode data fork from the on-disk format wiki
page into the kernel documentation.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-07-29 15:45:00 -04:00
Jonathan Corbet 2a7c7cba38 docs: Remove "could not extract kernel version" warning
This warning will happen for every normal kernel docs build and doesn't
carry any useful information.  Should anybody actually depend on this
"version" variable (which isn't clear to me), the "unknown version" value
will be clue enough.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-11 15:20:04 -07: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 9fdcd6afd8 docs-rst: conf.py: only setup notice box colors if Sphinx < 1.6
Sphinx 1.5 added a new way to change backward colors for note
boxes, but kept backward compatibility with 1.4. On Sphinx 1.6,
the old way stopped working, in favor of a new less hackish
way.

Unfortunately, this is currently too buggy to be used, and
the old way doesn't work anymore. So, we have no option but
to stick with boring notice boxes.

One example of such bug is the notice that it is inside
struct v4l2_plane, at the "bytesused" field.

At least, add a notice about how to use, as maybe some day
the bug will vanish.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-09-08 10:02:44 -06:00
Mauro Carvalho Chehab c4b326e1a6 docs-rst: conf.py: remove lscape from LaTeX preamble
Only the media book used this extension in the past, but
it is not required anymore.

Cleanup patch only.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-09-08 10:02:39 -06:00
Mauro Carvalho Chehab 646056ec3b docs-rst: fix verbatim font size on tables
On Sphinx 1.6, fancy boxes are used for verbatim. The sphinx.sty
sets verbatim font is always \small. That causes a problem
inside tables that use smaller fonts, as it can be too big for
the box.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-26 15:50:20 -06:00
Markus Heiser 0e4c2b7589 docs: fix minimal sphinx version in conf.py
according to what Documentation/doc-guide/sphinx.rst says::

  The ReST markups currently used by the Documentation/ files
  are meant to be built with ``Sphinx`` version 1.3 or upper.

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-24 13:33:25 -06:00
Mauro Carvalho Chehab 5148e6ab76 docs-rst: pdf: use same vertical margin on all Sphinx versions
Currently, on Sphinx up to version 1.4, pdf output uses a vertical
margin of 1 inch. For upper versions, it uses a margin of 0.5 inches.

That causes both page headers and footers to be very close to the margin
of the sheet. Not all printers support writing like that.

Also, there's no reason why the layout for newer versions would be
different than for previous ones.

So, standardize it, by always setting to 1 inch.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-24 13:23:31 -06:00
Mauro Carvalho Chehab 633d612bda Docs: Fix breakage with Sphinx 1.5 and upper
Commit 85c21e5c3e (docs-rst: better adjust margins and font size) added a
\usepackage{geometry} that conflicts with another inclusion deep within the
dependencies with newer versions of Sphinx, causing the the PDF build to fail
with a "conflicting parameters" error.

Detect the Sphinx version, using sphinxsetup for Sphinx versions 1.5 and
upper.

Fixes: 85c21e5c3e
[jc: Tweaked logic to exclude 1.5.x for x < 3 ]
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-06-23 13:45:37 -06:00
Jonathan Corbet cc11022191 Docs: Include the Latex "ifthen" package
Otherwise we get PDF build failures when LaTeX refused to acknowledge the
existence of \ifthenelse

Fixes: 41cff161fe
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-06-23 13:45:30 -06:00
Mauro Carvalho Chehab bffac837f3 docs-rst: convert sh book to ReST
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16 08:44:18 -03:00