#
b31274d5 |
|
01-Mar-2024 |
Lukas Bulwahn <lukas.bulwahn@gmail.com> |
docs: drop the version constraints for sphinx and dependencies As discussed (see Links), there is some inertia to move to the recent Sphinx versions for the doc build environment. As first step, drop the version constraints and the related comments. As sphinx depends on jinja2, jinja2 is pulled in automatically. So drop that. Then, the sphinx-pre-install script will fail though with: Can't get default sphinx version from ./Documentation/sphinx/requirements.txt at ./scripts/sphinx-pre-install line 305. The script simply expects to parse a version constraint with Sphinx in the requirements.txt. That version is used in the script for suggesting the virtualenv directory name. To suggest a virtualenv directory name, when there is no version given in the requirements.txt, one could try to guess the version that would be downloaded with 'pip install -r Documentation/sphinx/requirements.txt'. However, there seems no simple way to get that version without actually setting up the venv and running pip. So, instead, name the directory with the fixed name 'sphinx_latest'. Finally update the Sphinx build documentation to reflect this directory name change. Link: https://lore.kernel.org/linux-doc/874jf4m384.fsf@meer.lwn.net/ Link: https://lore.kernel.org/linux-doc/20240226093854.47830-1-lukas.bulwahn@gmail.com/ Reviewed-by: Akira Yokosawa <akiyks@gmail.com> Tested-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20240301141800.30218-1-lukas.bulwahn@gmail.com>
|
#
40be2369 |
|
04-Feb-2024 |
Thorsten Blum <thorsten.blum@toblux.com> |
Documentation: multiple .rst files: Fix grammar and more consistent formatting sphinx.rst: - Remove unnecessary newline - Fix grammar s/on/in/ - Fix grammar s/check/checks/ - Capitalize heading "The C domain" changes.rst: - Remove colon after "pahole" to be consistent with other entries howto.rst: - Fix grammar s/you will/will you/ - Hyphenate "real-world problems" Signed-off-by: Thorsten Blum <thorsten.blum@toblux.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240205000117.3285-1-thorsten.blum@toblux.com
|
#
3e893e16 |
|
08-Dec-2023 |
Jonathan Corbet <corbet@lwn.net> |
docs: Raise the minimum Sphinx requirement to 2.4.4 Commit 31abfdda6527 (docs: Deprecate use of Sphinx < 2.4.x) in 6.2 added a warning that support for older versions of Sphinx would be going away. There have been no complaints, so the time has come. Raise the minimum Sphinx version to 2.4.4 and clean out some compatibility code that we no longer need. Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/874jgs47fq.fsf@meer.lwn.net Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
86b17aaf |
|
27-Oct-2023 |
Vegard Nossum <vegard.nossum@oracle.com> |
docs: automarkup: linkify git revs There aren't a ton of references to commits in the documentation, but they do exist, and we can use automarkup to linkify them to make them easier to follow. Use something like this to find references to commits: git grep -P 'commit.*[0-9a-f]{8,}' Documentation/ Also fix a few of these to standardize on the exact format that is already used in changelogs. Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231027115420.205279-1-vegard.nossum@oracle.com
|
#
35d4a3c6 |
|
24-Apr-2023 |
Joe Stringer <joe@isovalent.com> |
docs/doc-guide: Clarify how to write tables Prior to this commit, the kernel docs writing guide spent over a page describing exactly how *not* to write tables into the kernel docs, without providing a example about the desired format. This patch provides a positive example first in the guide so that it's harder to miss, then leaves the existing less desirable approach below for contributors to follow if they have some stronger justification for why to use that approach. Signed-off-by: Joe Stringer <joe@isovalent.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/20230424171850.3612317-1-joe@isovalent.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
26d797ff |
|
27-Sep-2022 |
Jonathan Corbet <corbet@lwn.net> |
docs: update sphinx.rst to reflect the default theme change We don't default to Read The Docs anymore; update the docs to match. Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
679b4bc2 |
|
16-Sep-2022 |
Akira Yokosawa <akiyks@gmail.com> |
docs/doc-guide: Add documentation on SPHINX_IMGMATH Now that building html docs with math expressions does not need texlive packages, remove the note on the requirement in the "Sphinx Install" section. Instead, add sections of "Math Expressions in HTML" and "Choice of Math Renderer". Describe the effect of setting SPHINX_IMGMATH in the latter section. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/a67e3279-6bc7-ee2c-2b49-9275252460b0@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
4d627ef1 |
|
24-Jun-2022 |
Akira Yokosawa <akiyks@gmail.com> |
docs/doc-guide: Mention make variable SPHINXDIRS SPHINXDIRS is useful when you want to test build only those documents affected by your changes. Mention it in the "Sphinx Build" section. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Maciej W. Rozycki <macro@orcam.me.uk> Link: https://lore.kernel.org/r/50d6f0bc-030d-9529-0665-e2b3e7c792d8@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
7c43214d |
|
09-Jun-2022 |
Akira Yokosawa <akiyks@gmail.com> |
docs/doc-guide: Add footnote on Inkscape for better images in PDF documents With kernel releases v5.18 and later, if you have Inkscape, images embedded in PDF documents are of vector graphics, not the raster images as are the case with pre-v5.18 releases. Even with pre-5.18 releases, having Inkscape would improve images converted from some of SVG files which are not fully covered by the limited capability of rsvg-convert(1) [1]. Add a footnote mentioning the expected improvements of such images. Link: https://gitlab.gnome.org/GNOME/librsvg#non-goals-of-librsvg [1] Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/81cddbde-bc28-bec1-fca4-3c8fe2df502f@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
452c4915 |
|
28-Mar-2022 |
Bagas Sanjaya <bagasdotme@gmail.com> |
Documentation: sphinx: replace "Introduction" chapter heading with page title Replace first chapter heading ("Introduction") with page title named "Using Sphinx for kernel documentation". This way, the first-level TOC for doc-guide contains title instead of chapter headings for this page. Cc: Jonathan Corbet <corbet@lwn.net> Cc: "David S. Miller" <davem@davemloft.net> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Cc: Tony Nguyen <anthony.l.nguyen@intel.com> Cc: Vinod Koul <vkoul@kernel.org> Cc: Daniel Borkmann <daniel@iogearbox.net> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Cc: Akira Yokosawa <akiyks@gmail.com> Cc: "Rafael J. Wysocki" <rafael.j.wysocki@intel.com> Cc: Jens Axboe <axboe@kernel.dk> Cc: linux-kernel@vger.kernel.org Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
db67eb74 |
|
03-Jan-2022 |
Jonathan Corbet <corbet@lwn.net> |
docs: discourage use of list tables Our documentation encourages the use of list-table formats, but that advice runs counter to the objective of keeping the plain-text documentation as useful and readable as possible. Turn that advice around the other way so that people don't keep adding these tables. Acked-by: Christoph Hellwig <hch@lst.de> Acked-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
0e805b11 |
|
11-Dec-2021 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
docs: address some text issues with css/theme support Fix: - overriden ->overridden - some whitespace issues introduced at the css/theme Makefile help. Reported-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/b0b166025019f7cc4f122bd789c79ba28cc2d29d.1639212812.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
135707d3 |
|
07-Dec-2021 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
docs: allow to pass extra DOCS_CSS themes via make Specially when the RTD theme is not used, it makes sense to allow specifying extra CSS files via a make variable. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/03d09bf41ad39aa0abfe2ea3c879b09aa3a0948d.1638870323.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
fca7216b |
|
07-Dec-2021 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
docs: allow selecting a Sphinx theme Instead of having RTD as an almost mandatory theme, allow the user to select other themes via DOCS_THEME environment var. There's a catch, though: as the current theme override logic is dependent of the RTD theme, we need to move the code which adds the CSS overrides to be inside the RTD theme logic. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/bd20adabfd428fd3cd0e69c2cf146aa354932936.1638870323.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
6d6a8d6a |
|
10-Nov-2021 |
Akira Yokosawa <akiyks@gmail.com> |
docs: Update Sphinx requirements Commit f546ff0c0c07 ("Move our minimum Sphinx version to 1.7") raised the minimum version to 1.7. For pdfdocs, sphinx_pre_install says: note: If you want pdf, you need at least Sphinx 2.4.4. , and current requirements.txt installs Sphinx 2.4.4. Update Sphinx versions mentioned in docs and remove a note on earlier Sphinx versions. Update zh_CN and it_IT translations as well. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Federico Vaga <federico.vaga@vaga.pv.it> Cc: Alex Shi <alexs@kernel.org> Reviewed-by: Alex Shi <alexs@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
1e013ff7 |
|
27-Jan-2021 |
Nícolas F. R. A. Prado <nfraprado@protonmail.com> |
docs: Document cross-referencing using relative path Update the Cross-referencing section to explain how to create a cross-reference to a document using relative paths and with no additional syntax, by relying on automarkup.py. Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com> Link: https://lore.kernel.org/r/20210128010028.58541-3-nfraprado@protonmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
0be1511f |
|
28-Dec-2020 |
Randy Dunlap <rdunlap@infradead.org> |
Documentation: doc-guide: fixes to sphinx.rst Various fixes to sphinx.rst: - eliminate a double-space between 2 words - grammar/wording - punctuation - call rows in a table 'rows' instead of 'columns' (or does Sphinx call everything a column?) - It seems that "amdfonts" should be "amsfonts". I can't find any amdfonts. Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/20201228231212.22448-1-rdunlap@infradead.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
e0a45cda |
|
02-Dec-2020 |
Andrew Klychkov <andrew.a.klychkov@gmail.com> |
Documentation: fix typos found in process, dev-tools, and doc-guide subdirectories Fix four typos in kcov.rst, sphinx.rst, clang-format.rst, and embargoed-hardware-issues.rst Signed-off-by: Andrew Klychkov <andrew.a.klychkov@gmail.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Miguel Ojeda <ojeda@kernel.org> Link: https://lore.kernel.org/r/20201202075438.GA35516@spblnx124.lan Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
c170f2eb |
|
11-Sep-2020 |
Nícolas F. R. A. Prado <nfraprado@protonmail.com> |
docs: Document cross-referencing between documentation pages The syntax to cross-reference between documentation pages wasn't documented anywhere. Document the cross-referencing using the new automarkup for Documentation/... and also Sphinx's doc directive for using relative paths. Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com> Link: https://lore.kernel.org/r/20200911133339.327721-4-nfraprado@protonmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
d9d7c0c4 |
|
26-Jun-2019 |
Jonathan Corbet <corbet@lwn.net> |
docs: Note that :c:func: should no longer be used Now that we can mark up function() automatically, there is no reason to use :c:func: and every reason to avoid it. Adjust the documentation to reflect that fact. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
83e8b971 |
|
11-Jun-2019 |
André Almeida <andrealmeid@collabora.com> |
sphinx.rst: Add note about code snippets embedded in the text There's a paragraph that explains how to create fixed width text block, but it doesn't explains how to create fixed width text inline, although this feature is really used through the documentation. Fix that adding a quick note about it. Signed-off-by: André Almeida <andrealmeid@collabora.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
a700767a |
|
29-May-2019 |
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> |
docs: requirements.txt: recommend Sphinx 1.7.9 As discussed at the linux-doc ML, while we'll still support version 1.3, it is time to recommend a more modern version. So, let's switch the minimal requirements to Sphinx 1.7.9, as it has the "-jauto" flag, with makes a lot faster when building documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
4d01460e |
|
14-Jan-2019 |
Joel Nider <joeln@il.ibm.com> |
docs-rst: doc-guide: Minor grammar fixes While using this guide to learn the new documentation method, I saw a few phrases that I felt could be improved. These small changes improve the grammar and choice of words to further enhance the installation instructions. Signed-off-by: Joel Nider <joeln@il.ibm.com> Acked-by: Mike Rapoport <rppt@linux.ibm.com> Acked-by: Matthew Wilcox <willy@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
f77af637 |
|
20-Nov-2018 |
Federico Vaga <federico.vaga@vaga.pv.it> |
doc:process: add links where missing Some documents are refering to others without links. With this patch I add those missing links. This patch affects only documents under process/ and labels where necessary. Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
c1ec85ff |
|
05-Jun-2018 |
Federico Vaga <federico.vaga@vaga.pv.it> |
doc:doc-guide: fix a typo and an error Fix a typo in sphinx.rst and a minor error in parse-header.rst Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
95a40b86 |
|
26-Aug-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
sphinx.rst: Allow Sphinx version 1.6 at the docs Now that the PDF building issues with Sphinx 1.6 got fixed, update the documentation and scripts accordingly. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
868366aa |
|
17-Jul-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
sphinx.rst: document scripts/sphinx-pre-install script Now that we have a script to check for Sphinx dependencies, document it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
6e322a17 |
|
14-Jul-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
sphinx.rst: better organize the documentation about PDF build Instead of having it on just one note, add a separate section. This way, we could later improve it, providing a better guide about the needed steps for PDF builds. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
d43e5ae9 |
|
14-Jul-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
sphinx.rst: describe the install requirements for kfigure As we now have a document describing the install requirements for Sphinx, add there the need for GraphViz and ImageMagick. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
29fd35bd |
|
14-Jul-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
sphinx.rst: fix unknown reference There's no "Sphinx C Domain" reference at the Kernel documentation. So, don't use references for it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
58ef4a42 |
|
14-Jul-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
sphinx.rst: explain the usage of virtual environment As the Sphinx build seems very fragile, specially for PDF output, add a notice about how to use it on a virtual environment. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
b8b07b5c |
|
14-Jul-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
docs-rst: move Sphinx install instructions to sphinx.rst The toolchain used by Sphinx is somewhat complex, and installing it should be part of the doc-guide. Move it out of changes.rst. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
ff41c419 |
|
14-May-2017 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
docs: update old references for DocBook from the documentation DocBook is mentioned several times at the documentation. Update the obsolete references from it at the DocBook. Acked-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
#
db6ccf23 |
|
06-Mar-2017 |
Markus Heiser <markus.heiser@darmarit.de> |
docs-rst: automatically convert Graphviz and SVG images This patch brings scalable figure, image handling and a concept to embed *render* markups: * DOT (http://www.graphviz.org) * SVG For image handling use the 'image' replacement:: .. kernel-image:: svg_image.svg :alt: simple SVG image For figure handling use the 'figure' replacement:: .. kernel-figure:: svg_image.svg :alt: simple SVG image SVG image example Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the *render* directive.:: .. kernel-render:: DOT :alt: foobar digraph :caption: Embedded **DOT** (Graphviz) code. digraph foo { "bar" -> "baz"; } The *render* directive is a concept to integrate *render* markups and languages, yet supported markups: * DOT: render embedded Graphviz's **DOT** * SVG: render embedded Scalable Vector Graphics (**SVG**) Cc: Jani Nikula <jani.nikula@linux.intel.com> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Tested-by: Daniel Vetter <daniel.vetter@ffwll.ch> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> (v2 - v5) Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> (v1, v6) Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
c3c53600 |
|
02-Mar-2017 |
Daniel Vetter <daniel.vetter@ffwll.ch> |
doc: Explain light-handed markup preference a bit better We're still pretty far away from anything like a consensus, but there's clearly a lot of people who prefer an as-light as possible approach to converting existing .txt files to .rst. Make sure this is properly taken into account and clear. Motivated by discussions with Peter and Christoph and others. Cc: Christoph Hellwig <hch@infradead.org> Cc: Peter Zijlstra <peterz@infradead.org> Cc: Jani Nikula <jani.nikula@linux.intel.com> Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
#
1dc4bbf0 |
|
17-Nov-2016 |
Mauro Carvalho Chehab <mchehab@kernel.org> |
docs-rst: doc-guide: split the kernel-documentation.rst contents Having the kernel-documentation at the topmost level doesn't allow generating a separate PDF file for it. Also, makes harder to add extra contents. So, place it on a sub-dir. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|