aboutsummaryrefslogtreecommitdiff
path: root/Documentation/doc-guide
AgeCommit message (Collapse)Author
2020-06-10Merge tag 'docs-5.8-2' of git://git.lwn.net/linuxLinus Torvalds
Pull more documentation updates from Jonathan Corbet: "A handful of late-arriving docs fixes, along with a patch changing a lot of HTTP links to HTTPS that had to be yanked and redone before the first pull" * tag 'docs-5.8-2' of git://git.lwn.net/linux: docs/memory-barriers.txt/kokr: smp_mb__{before,after}_atomic(): update Documentation Documentation: devres: add missing entry for devm_platform_get_and_ioremap_resource() Replace HTTP links with HTTPS ones: documentation docs: it_IT: address invalid reference warnings doc: zh_CN: use doc reference to resolve undefined label warning docs: Update the location of the LF NDA program docs: dev-tools: coccinelle: underlines
2020-06-08Replace HTTP links with HTTPS ones: documentationAlexander A. Klimov
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-03Merge tag 'media/v5.8-1' of ↵Linus Torvalds
git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media Pull media updates from Mauro Carvalho Chehab: - Media documentation is now split into admin-guide, driver-api and userspace-api books (a longstanding request from Jon); - The media Kconfig was reorganized, in order to make easier to select drivers and their dependencies; - The testing drivers now has a separate directory; - added a new driver for Rockchip Video Decoder IP; - The atomisp staging driver was resurrected. It is meant to work with 4 generations of cameras on Atom-based laptops, tablets and cell phones. So, it seems worth investing time to cleanup this driver and making it in good shape. - Added some V4L2 core ancillary routines to help with h264 codecs; - Added an ov2740 image sensor driver; - The si2157 gained support for Analog TV, which, in turn, added support for some cx231xx and cx23885 boards to also support analog standards; - Added some V4L2 controls (V4L2_CID_CAMERA_ORIENTATION and V4L2_CID_CAMERA_SENSOR_ROTATION) to help identifying where the camera is located at the device; - VIDIOC_ENUM_FMT was extended to support MC-centric devices; - Lots of drivers improvements and cleanups. * tag 'media/v5.8-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (503 commits) media: Documentation: media: Refer to mbus format documentation from CSI-2 docs media: s5k5baf: Replace zero-length array with flexible-array media: i2c: imx219: Drop <linux/clk-provider.h> and <linux/clkdev.h> media: i2c: Add ov2740 image sensor driver media: ov8856: Implement sensor module revision identification media: ov8856: Add devicetree support media: dt-bindings: ov8856: Document YAML bindings media: dvb-usb: Add Cinergy S2 PCIe Dual Port support media: dvbdev: Fix tuner->demod media controller link media: dt-bindings: phy: phy-rockchip-dphy-rx0: move rockchip dphy rx0 bindings out of staging media: staging: dt-bindings: phy-rockchip-dphy-rx0: remove non-used reg property media: atomisp: unify the version for isp2401 a0 and b0 versions media: atomisp: update TODO with the current data media: atomisp: adjust some code at sh_css that could be broken media: atomisp: don't produce errs for ignored IRQs media: atomisp: print IRQ when debugging media: atomisp: isp_mmu: don't use kmem_cache media: atomisp: add a notice about possible leak resources media: atomisp: disable the dynamic and reserved pools media: atomisp: turn on camera before setting it ...
2020-04-20docs: fix broken references for ReST files that moved aroundMauro Carvalho Chehab
Some broken references happened due to shifting files around and ReST renames. Those can't be auto-fixed by the script, so let's fix them manually. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Corentin Labbe <clabbe.montjoie@gmail.com> Link: https://lore.kernel.org/r/64773a12b4410aaf3e3be89e3ec7e34de2484eea.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-14media: docs: move uAPI book to userspace-api/mediaMauro Carvalho Chehab
Since 2017, there is an space reserved for userspace API, created by changeset 1d596dee3862 ("docs: Create a user-space API guide"). As the media subsystem was one of the first subsystems to use Sphinx, until this patch, we were keeping things on a separate place. Let's just use the new location, as having all uAPI altogether will likely make things easier for developers. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-02-05Documentation: build warnings related to missing blank lines after explicit ↵Sameer Rahmani
markups has been fixed Fix for several documentation build warnings related to missing blank lines after explicit mark up. Exact warning message: WARNING: Explicit markup ends without a blank line; unexpected unindent. Signed-off-by: Sameer Rahmani <lxsameer@gnu.org> Link: https://lore.kernel.org/r/20200203201543.24834-1-lxsameer@gnu.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-01-24Add a maintainer entry profile for documentationJonathan Corbet
Documentation should lead by example, so here's a basic maintainer entry profile for this subsystem. Reviewed-by: Matthew Wilcox (Oracle) <willy@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-01-24Add a document on how to contribute to the documentationJonathan Corbet
This is mostly a collection of thoughts for how people who want to help out can make the docs better. Hopefully the world will respond with a flurry of useful patches. Acked-by: Jani Nikula <jani.nikula@intel.com> Reviewed-by: Matthew Wilcox (Oracle) <willy@infradead.org> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-11-07kernel-doc: rename the kernel-doc directive 'functions' to 'identifiers'Changbin Du
The 'functions' directive is not only for functions, but also works for structs/unions. So the name is misleading. This patch renames it to 'identifiers', which specific the functions/types to be included in documentation. We keep the old name as an alias of the new one before all documentation are updated. Signed-off-by: Changbin Du <changbin.du@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-07-17docs: remove extra conf.py filesMauro Carvalho Chehab
Now that the latex_documents are handled automatically, we can remove those extra conf.py files. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-06-28Doc : doc-guide : Fix a typoSheriff Esseson
fix the disjunction by replacing "of" with "or". Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-06-26docs: Note that :c:func: should no longer be usedJonathan Corbet
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>
2019-06-14sphinx.rst: Add note about code snippets embedded in the textAndré Almeida
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>
2019-05-30docs: requirements.txt: recommend Sphinx 1.7.9Mauro Carvalho Chehab
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>
2019-04-19docs: doc-guide: remove the extension from .rst filesMauro Carvalho Chehab
On almost all places, we're including ReST files without the extension. Let's remove the extension here as well, in order to use just one standard. Suggested-by: Jani Nikula <jani.nikula@linux.intel.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-02-17docs: kernel-doc: typo "if ... if" -> "if ... is"Frank Rowand
"If no *function* if specified" should instead be "If no *function* is specified". Reported-by: Matthew Wilcox <willy@infradead.org> Signed-off-by: Frank Rowand <frank.rowand@sony.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-02-01docs: kernel-doc: typo "documentaion"Frank Rowand
Fix a typo in kernel-doc.rst Signed-off-by: Frank Rowand <frank.rowand@sony.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-02-01docs: kernel-doc: update commands to generate man pageFrank Rowand
(1) The command to generate man pages is truncated in the pdf version of the document. Reformat the command into multiple lines to prevent the truncation. (2) Older versions of git do not support all variants of pathspec syntax. Provide commands to generate man pages for various alternate syntax. Signed-off-by: Frank Rowand <frank.rowand@sony.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-01-14docs-rst: doc-guide: Minor grammar fixesJoel Nider
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>
2018-12-06doc:process: add links where missingFederico Vaga
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>
2018-11-07doc-guide:kernel-doc.rst: Reference to foobarJoris Gutjahr
In the Function documentation Section of kernel-doc.rst there is a function_name() function as an example for how to make a comment about a function. But at the end of that example there is a reference to foobar instead of function_name. I think that should rather be function_name, because that was the placeholder the whole example was using. Signed-off-by: Joris Gutjahr <joris.gutjahr@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-30Documentation/sphinx: allow "functions" with no parametersMike Rapoport
When kernel-doc:: specified in .rst document without explicit directives, it outputs both comment and DOC: sections. If a DOC: section was explicitly included in the same document it will be duplicated. For example, the output generated for Documentation/core-api/idr.rst [1] has "IDA description" in the "IDA usage" section and in the middle of the API reference. This patch enables using "functions" directive without parameters to output all the documentation excluding DOC: sections. [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com> Acked-by: Matthew Wilcox <willy@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-26doc:sphinx: fix parse-header descriptionFederico Vaga
The description speaks about the option ``--man`` but it does not exist. Instead, there is the option ``--usage`` $ ./Documentation/sphinx/parse-headers.pl --man Unknown option: man Usage: parse_headers.pl [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] Where <options> can be: --debug, --help or --man. Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-26doc:doc-guide: fix a typo and an errorFederico Vaga
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>
2018-05-04MAINTAINERS & files: Canonize the e-mails I use at filesMauro Carvalho Chehab
From now on, I'll start using my @kernel.org as my development e-mail. As such, let's remove the entries that point to the old mchehab@s-opensource.com at MAINTAINERS file. For the files written with a copyright with mchehab@s-opensource, let's keep Samsung on their names, using mchehab+samsung@kernel.org, in order to keep pointing to my employer, with sponsors the work. For the files written before I join Samsung (on July, 4 2013), let's just use mchehab@kernel.org. For bug reports, we can simply point to just kernel.org, as this will reach my mchehab+samsung inbox anyway. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Brian Warner <brian.warner@samsung.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2018-02-23doc-guide: kernel-doc: add comment about formatting verificationMike Rapoport
Currently there is no automated checking for kernel-doc comments except running 'kernel-doc -v -none <filename>'. Mention the possibility to run kernel-doc to verify formatting of the comments in the kernel-doc guide. Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-18doc-guide: kernel-doc: add examples about nested union/structsMauro Carvalho Chehab
It helps to give some examples about how to use in-line comments also when nested union/structs are present. So add it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-18doc-guide: kernel-doc: move in-line section to be after nested structMauro Carvalho Chehab
We want to give some examples about how to do in-line comments for nested structs. So, move it to be after nested structs/unions chapter. The section content was not changed on this patch. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-18doc-guide: kernel-doc: fix example for inlined commentsMauro Carvalho Chehab
Without ending with a ";", kernel-doc doesn't recognize it as an struct, and it fails to parse the example. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-18doc-guide: kernel-doc: fix example for nested_foobar structMauro Carvalho Chehab
There's a missing */ at the end of Kernel docs example. Even adding it, it will still produce 3 warnings: example:33: warning: Function parameter or member 'bar' not described in 'nested_foobar' example:33: warning: Function parameter or member 'bar.st1' not described in 'nested_foobar' example:33: warning: Function parameter or member 'bar.st2' not described in 'nested_foobar' So, make the example more complete and add the missing end of comment there. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-13Restructure kernel-doc.rstMatthew Wilcox
I found the layout confusing with multiple introductions to what kernel-doc is and how to use it. I made the following changes: - Moved the 'Including kernel-doc comments' section to the end of the document -- we should explain what it *is* before we explain how to integrate it. - Moved the 'Recommendations' subsection to the top. We want people to know what to document before telling them how to do it. - Rewrite the 'Writing kernel-doc comments' section, integrating the 'Recommendations' subsection and a paragraph from 'How to format kernel-doc comments'. - Remove the paragraph about the kernel-doc script; we're supposed to be teaching people how to use punctuation to write pretty documentation, not documenting the build tooling. - Split the 'Parameters and member arguments' section into 'Function parameters' and 'Members'. Structure members are not commonly referred to as arguments. - Integrate the 'private:' and 'public:' tag descriptions into the 'Members' section. - Move the 'In-line member documentation comments' subsection up to be with the 'Members' section. Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-13Fix whitespace in exampleMatthew Wilcox
Line up the second line in the way that the example purports to be showing. Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-13Add scripts/split-man.plMatthew Wilcox
Instead of asking the user to copy and paste a small perl script from the documentation, just distribute the perl script in the scripts directory. Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-13Minor fixes to kernel-doc.rstMatthew Wilcox
The author clearly meant to use the word 'which' here. Also replace some tabs with spaces which fixes the syntax highlighting in my editor. Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-13Add documentation for Context sectionMatthew Wilcox
This section is mentioned in scripts/kernel-doc, so we should mention it in doc-guide/kernel-doc.rst. There are close to 500 comments using the Context section already, and almost 300 using a Locking section which fulfills much the same purpose (and should probably be converted for consistency). Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21scripts: kernel-doc: parse next structs/unionsMauro Carvalho Chehab
There are several places within the Kernel tree with nested structs/unions, like this one: struct ingenic_cgu_clk_info { const char *name; enum { CGU_CLK_NONE = 0, CGU_CLK_EXT = BIT(0), CGU_CLK_PLL = BIT(1), CGU_CLK_GATE = BIT(2), CGU_CLK_MUX = BIT(3), CGU_CLK_MUX_GLITCHFREE = BIT(4), CGU_CLK_DIV = BIT(5), CGU_CLK_FIXDIV = BIT(6), CGU_CLK_CUSTOM = BIT(7), } type; int parents[4]; union { struct ingenic_cgu_pll_info pll; struct { struct ingenic_cgu_gate_info gate; struct ingenic_cgu_mux_info mux; struct ingenic_cgu_div_info div; struct ingenic_cgu_fixdiv_info fixdiv; }; struct ingenic_cgu_custom_info custom; }; }; Currently, such struct is documented as: **Definition** :: struct ingenic_cgu_clk_info { const char * name; }; **Members** ``name`` name of the clock With is obvioulsy wrong. It also generates an error: drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum' However, there's nothing wrong with this kernel-doc markup: everything is documented there. It makes sense to document all fields there. So, add a way for the core to parse those structs. With this patch, all documented fields will properly generate documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21docs: kernel-doc.rst: add documentation about man pagesMauro Carvalho Chehab
kernel-doc-nano-HOWTO.txt has a chapter about man pages production. While we don't have a working "make manpages" target, add it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21docs: kernel-doc.rst: improve typedef documentationMauro Carvalho Chehab
Add documentation about typedefs for function prototypes and move it to happen earlier. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21docs: kernel-doc.rst: improve structs chapterMauro Carvalho Chehab
There is a mess on this chapter: it suggests that even enums and unions should be documented with "struct". That's not the way it should be ;-) Fix it and move it to happen earlier. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21docs: kernel-doc.rst: improve function documentation sectionMauro Carvalho Chehab
Move its contents to happen earlier and improve the description of return values, adding a subsection to it. Most of the contents there came from kernel-doc-nano-HOWTO.txt. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21docs: kernel-doc.rst: improve private members descriptionMauro Carvalho Chehab
The private members section can now be moved to be together with the arguments section. Move it there and add an example about the usage of public: Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21docs: kernel-doc.rst: better describe kernel-doc argumentsMauro Carvalho Chehab
Add a new section to describe kernel-doc arguments, adding examples about how identation should happen, as failing to do that causes Sphinx to do the wrong thing. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-10-19Documentation: fix ref to sphinx/kerneldoc.pyTom Saeger
Signed-off-by: Tom Saeger <tom.saeger@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-26sphinx.rst: Allow Sphinx version 1.6 at the docsMauro Carvalho Chehab
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>
2017-07-23sphinx.rst: document scripts/sphinx-pre-install scriptMauro Carvalho Chehab
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>
2017-07-17sphinx.rst: better organize the documentation about PDF buildMauro Carvalho Chehab
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>
2017-07-17sphinx.rst: describe the install requirements for kfigureMauro Carvalho Chehab
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>
2017-07-17sphinx.rst: fix unknown referenceMauro Carvalho Chehab
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>
2017-07-17sphinx.rst: explain the usage of virtual environmentMauro Carvalho Chehab
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>
2017-07-17docs-rst: move Sphinx install instructions to sphinx.rstMauro Carvalho Chehab
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>