Merge tag 'docs-4.10' of git://git.lwn.net/linux
Pull documentation update from Jonathan Corbet:
"These are the documentation changes for 4.10.
It's another busy cycle for the docs tree, as the sphinx conversion
continues. Highlights include:
- Further work on PDF output, which remains a bit of a pain but
should be more solid now.
- Five more DocBook template files converted to Sphinx. Only 27 to
go... Lots of plain-text files have also been converted and
integrated.
- Images in binary formats have been replaced with more
source-friendly versions.
- Various bits of organizational work, including the renaming of
various files discussed at the kernel summit.
- New documentation for the device_link mechanism.
... and, of course, lots of typo fixes and small updates"
* tag 'docs-4.10' of git://git.lwn.net/linux: (193 commits)
dma-buf: Extract dma-buf.rst
Update Documentation/00-INDEX
docs: 00-INDEX: document directories/files with no docs
docs: 00-INDEX: remove non-existing entries
docs: 00-INDEX: add missing entries for documentation files/dirs
docs: 00-INDEX: consolidate process/ and admin-guide/ description
scripts: add a script to check if Documentation/00-INDEX is sane
Docs: change sh -> awk in REPORTING-BUGS
Documentation/core-api/device_link: Add initial documentation
core-api: remove an unexpected unident
ppc/idle: Add documentation for powersave=off
Doc: Correct typo, "Introdution" => "Introduction"
Documentation/atomic_ops.txt: convert to ReST markup
Documentation/local_ops.txt: convert to ReST markup
Documentation/assoc_array.txt: convert to ReST markup
docs-rst: parse-headers.pl: cleanup the documentation
docs-rst: fix media cleandocs target
docs-rst: media/Makefile: reorganize the rules
docs-rst: media: build SVG from graphviz files
docs-rst: replace bayer.png by a SVG image
...
This commit is contained in:
Linus Torvalds
66
scripts/check_00index.sh
Executable file
66
scripts/check_00index.sh
Executable file
@@ -0,0 +1,66 @@
|
||||
#!/bin/bash
|
||||
|
||||
cd Documentation/
|
||||
|
||||
# Check entries that should be removed
|
||||
|
||||
obsolete=""
|
||||
for i in $(tail -n +12 00-INDEX |grep -E '^[a-zA-Z0-9]+'); do
|
||||
if [ ! -e $i ]; then
|
||||
obsolete="$obsolete $i"
|
||||
fi
|
||||
done
|
||||
|
||||
# Check directory entries that should be added
|
||||
search=""
|
||||
dir=""
|
||||
for i in $(find . -maxdepth 1 -type d); do
|
||||
if [ "$i" != "." ]; then
|
||||
new=$(echo $i|perl -ne 's,./(.*),$1/,; print $_')
|
||||
search="$search $new"
|
||||
fi
|
||||
done
|
||||
|
||||
for i in $search; do
|
||||
if [ "$(grep -P "^$i" 00-INDEX)" == "" ]; then
|
||||
dir="$dir $i"
|
||||
fi
|
||||
done
|
||||
|
||||
# Check file entries that should be added
|
||||
search=""
|
||||
file=""
|
||||
for i in $(find . -maxdepth 1 -type f); do
|
||||
if [ "$i" != "./.gitignore" ]; then
|
||||
new=$(echo $i|perl -ne 's,./(.*),$1,; print $_')
|
||||
search="$search $new"
|
||||
fi
|
||||
done
|
||||
|
||||
for i in $search; do
|
||||
if [ "$(grep -P "^$i\$" 00-INDEX)" == "" ]; then
|
||||
file="$file $i"
|
||||
fi
|
||||
done
|
||||
|
||||
# Output its findings
|
||||
|
||||
echo -e "Documentation/00-INDEX check results:\n"
|
||||
|
||||
if [ "$obsolete" != "" ]; then
|
||||
echo -e "- Should remove those entries:\n\t$obsolete\n"
|
||||
else
|
||||
echo -e "- No obsolete entries\n"
|
||||
fi
|
||||
|
||||
if [ "$dir" != "" ]; then
|
||||
echo -e "- Should document those directories:\n\t$dir\n"
|
||||
else
|
||||
echo -e "- No new directories to add\n"
|
||||
fi
|
||||
|
||||
if [ "$file" != "" ]; then
|
||||
echo -e "- Should document those files:\n\t$file"
|
||||
else
|
||||
echo "- No new files to add"
|
||||
fi
|
||||
@@ -2187,7 +2187,7 @@ sub process {
|
||||
|
||||
if ($rawline=~/^\+\+\+\s+(\S+)/) {
|
||||
$setup_docs = 0;
|
||||
if ($1 =~ m@Documentation/kernel-parameters.txt$@) {
|
||||
if ($1 =~ m@Documentation/admin-guide/kernel-parameters.rst$@) {
|
||||
$setup_docs = 1;
|
||||
}
|
||||
#next;
|
||||
@@ -5115,7 +5115,7 @@ sub process {
|
||||
my $asm_volatile = qr{\b(__asm__|asm)\s+(__volatile__|volatile)\b};
|
||||
if ($line =~ /\bvolatile\b/ && $line !~ /$asm_volatile/) {
|
||||
WARN("VOLATILE",
|
||||
"Use of volatile is usually wrong: see Documentation/volatile-considered-harmful.txt\n" . $herecurr);
|
||||
"Use of volatile is usually wrong: see Documentation/process/volatile-considered-harmful.rst\n" . $herecurr);
|
||||
}
|
||||
|
||||
# Check for user-visible strings broken across lines, which breaks the ability
|
||||
@@ -5831,7 +5831,7 @@ sub process {
|
||||
|
||||
if (!grep(/$name/, @setup_docs)) {
|
||||
CHK("UNDOCUMENTED_SETUP",
|
||||
"__setup appears un-documented -- check Documentation/kernel-parameters.txt\n" . $herecurr);
|
||||
"__setup appears un-documented -- check Documentation/admin-guide/kernel-parameters.rst\n" . $herecurr);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -204,6 +204,7 @@ EOF
|
||||
|
||||
## init lots of data
|
||||
|
||||
|
||||
my $errors = 0;
|
||||
my $warnings = 0;
|
||||
my $anon_struct_union = 0;
|
||||
@@ -211,7 +212,7 @@ my $anon_struct_union = 0;
|
||||
# match expressions used to find embedded type information
|
||||
my $type_constant = '\%([-_\w]+)';
|
||||
my $type_func = '(\w+)\(\)';
|
||||
my $type_param = '\@(\w+)';
|
||||
my $type_param = '\@(\w+(\.\.\.)?)';
|
||||
my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
|
||||
my $type_struct = '\&((struct\s*)*[_\w]+)';
|
||||
my $type_struct_xml = '\\&((struct\s*)*[_\w]+)';
|
||||
@@ -420,6 +421,7 @@ my $doc_block = $doc_com . 'DOC:\s*(.*)?';
|
||||
my $doc_inline_start = '^\s*/\*\*\s*$';
|
||||
my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
|
||||
my $doc_inline_end = '^\s*\*/\s*$';
|
||||
my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
|
||||
my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
|
||||
|
||||
my %parameterdescs;
|
||||
@@ -2353,7 +2355,10 @@ sub push_parameter($$$) {
|
||||
|
||||
if ($type eq "" && $param =~ /\.\.\.$/)
|
||||
{
|
||||
$param = "...";
|
||||
if (!$param =~ /\w\.\.\.$/) {
|
||||
# handles unnamed variable parameters
|
||||
$param = "...";
|
||||
}
|
||||
if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
|
||||
$parameterdescs{$param} = "variable arguments";
|
||||
}
|
||||
@@ -3020,7 +3025,16 @@ sub process_file($) {
|
||||
}
|
||||
}
|
||||
} elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
|
||||
if (/$doc_inline_start/) {
|
||||
if (/$doc_inline_oneline/) {
|
||||
$section = $1;
|
||||
$contents = $2;
|
||||
if ($contents ne "") {
|
||||
$contents .= "\n";
|
||||
dump_section($file, $section, xml_escape($contents));
|
||||
$section = $section_default;
|
||||
$contents = "";
|
||||
}
|
||||
} elsif (/$doc_inline_start/) {
|
||||
$state = STATE_INLINE;
|
||||
$inline_doc_state = STATE_INLINE_NAME;
|
||||
} elsif ($decl_type eq 'function') {
|
||||
|
||||
Reference in New Issue
Block a user