[RFC PATCH v1 4/6] kernel-doc: insert TODOs on kernel-doc errors
From: Markus Heiser
Date: Tue Jan 24 2017 - 14:55:38 EST
The rstKernelDoc.py sphinx-extensions inserts '.. todo::' on
errors. With this patch sphinx.ext.todo extension [1] is activated.
This is similar to what we know from DocBook's *Oops* functionality of
the kernel-doc perl script [2].
I added this functionality (only) to the subproject, to left the main
build untouched. E.g. run::
make SPHINXDIRS="driver-api" htmldocs
open the HTML output and scroll down to see those *Oops* (TODO) boxes.
The *Oops* in the HTML output helps authors to find rough errors and
increase the quality of the documentation. ATM there are to many
errors (false positives) and it needs some discussion. Take this as a
starting point.
[1] http://www.sphinx-doc.org/en/stable/ext/todo.html
[2] http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/kernel-doc#n3073
Signed-off-by: Markus Heiser <markus.heiser@xxxxxxxxxxx>
---
Documentation/admin-guide/conf.py | 2 ++
Documentation/admin-guide/index.rst | 2 ++
Documentation/conf.py | 3 ++-
Documentation/core-api/conf.py | 2 ++
Documentation/core-api/index.rst | 2 ++
Documentation/dev-tools/conf.py | 2 ++
Documentation/dev-tools/index.rst | 2 ++
Documentation/doc-guide/conf.py | 2 ++
Documentation/doc-guide/index.rst | 2 ++
Documentation/driver-api/conf.py | 2 ++
Documentation/driver-api/index.rst | 2 ++
Documentation/gpu/conf.py | 2 ++
Documentation/gpu/index.rst | 2 ++
Documentation/media/conf.py | 2 ++
Documentation/media/index.rst | 2 ++
Documentation/process/conf.py | 2 ++
Documentation/process/index.rst | 2 ++
Documentation/security/conf.py | 2 ++
Documentation/security/index.rst | 9 +++++++++
19 files changed, 45 insertions(+), 1 deletion(-)
diff --git a/Documentation/admin-guide/conf.py b/Documentation/admin-guide/conf.py
index 86f7389..28993c4 100644
--- a/Documentation/admin-guide/conf.py
+++ b/Documentation/admin-guide/conf.py
@@ -8,3 +8,5 @@ latex_documents = [
('index', 'linux-user.tex', 'Linux Kernel User Documentation',
'The kernel development community', 'manual'),
]
+
+todo_include_todos = True
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 8ddae4e..8c9245a 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -67,3 +67,5 @@ configure specific aspects of kernel behavior to your liking.
=======
* :ref:`genindex`
+
+ .. todolist::
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 4843903..013af9a 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -34,7 +34,8 @@ from load_config import loadConfig
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['rstKernelDoc', 'rstFlatTable', 'kernel_include', 'cdomain' ]
+extensions = ['rstKernelDoc', 'rstFlatTable', 'kernel_include', 'cdomain',
+ 'sphinx.ext.todo' ]
# The name of the math extension changed on Sphinx 1.4
if major == 1 and minor > 3:
diff --git a/Documentation/core-api/conf.py b/Documentation/core-api/conf.py
index db1f765..55e1a0e 100644
--- a/Documentation/core-api/conf.py
+++ b/Documentation/core-api/conf.py
@@ -8,3 +8,5 @@ latex_documents = [
('index', 'core-api.tex', project,
'The kernel development community', 'manual'),
]
+
+todo_include_todos = True
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 0d93d80..e958124 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -32,3 +32,5 @@ Interfaces for kernel debugging
=======
* :ref:`genindex`
+
+ .. todolist::
diff --git a/Documentation/dev-tools/conf.py b/Documentation/dev-tools/conf.py
index 7faafa3..f9d394b 100644
--- a/Documentation/dev-tools/conf.py
+++ b/Documentation/dev-tools/conf.py
@@ -8,3 +8,5 @@ latex_documents = [
('index', 'dev-tools.tex', project,
'The kernel development community', 'manual'),
]
+
+todo_include_todos = True
diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
index 07d8811..48ffb70 100644
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -31,3 +31,5 @@ whole; patches welcome!
=======
* :ref:`genindex`
+
+ .. todolist::
diff --git a/Documentation/doc-guide/conf.py b/Documentation/doc-guide/conf.py
index fd37311..8f2af2e 100644
--- a/Documentation/doc-guide/conf.py
+++ b/Documentation/doc-guide/conf.py
@@ -8,3 +8,5 @@ latex_documents = [
('index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
'The kernel development community', 'manual'),
]
+
+todo_include_todos = True
diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
index 6fff402..b177a4e 100644
--- a/Documentation/doc-guide/index.rst
+++ b/Documentation/doc-guide/index.rst
@@ -18,3 +18,5 @@ How to write kernel documentation
=======
* :ref:`genindex`
+
+ .. todolist::
diff --git a/Documentation/driver-api/conf.py b/Documentation/driver-api/conf.py
index 202726d..b682e5c 100644
--- a/Documentation/driver-api/conf.py
+++ b/Documentation/driver-api/conf.py
@@ -8,3 +8,5 @@ latex_documents = [
('index', 'driver-api.tex', project,
'The kernel development community', 'manual'),
]
+
+todo_include_todos = True
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index a2e5db0..ebc86cb 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -38,3 +38,5 @@ available subsections can be seen below.
=======
* :ref:`genindex`
+
+ .. todolist::
diff --git a/Documentation/gpu/conf.py b/Documentation/gpu/conf.py
index 1757b04..44dc0c2 100644
--- a/Documentation/gpu/conf.py
+++ b/Documentation/gpu/conf.py
@@ -8,3 +8,5 @@ latex_documents = [
('index', 'gpu.tex', project,
'The kernel development community', 'manual'),
]
+
+todo_include_todos = True
diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
index 367d7c3..fee1857 100644
--- a/Documentation/gpu/index.rst
+++ b/Documentation/gpu/index.rst
@@ -20,3 +20,5 @@ Linux GPU Driver Developer's Guide
=======
* :ref:`genindex`
+
+ .. todolist::
diff --git a/Documentation/media/conf.py b/Documentation/media/conf.py
index bef927b..09755f9 100644
--- a/Documentation/media/conf.py
+++ b/Documentation/media/conf.py
@@ -8,3 +8,5 @@ latex_documents = [
('index', 'media.tex', 'Linux Media Subsystem Documentation',
'The kernel development community', 'manual'),
]
+
+todo_include_todos = True
diff --git a/Documentation/media/index.rst b/Documentation/media/index.rst
index 7f8f0af..eb2754d 100644
--- a/Documentation/media/index.rst
+++ b/Documentation/media/index.rst
@@ -17,3 +17,5 @@ Contents:
=======
* :ref:`genindex`
+
+ .. todolist::
diff --git a/Documentation/process/conf.py b/Documentation/process/conf.py
index 1b01a80..a322314 100644
--- a/Documentation/process/conf.py
+++ b/Documentation/process/conf.py
@@ -8,3 +8,5 @@ latex_documents = [
('index', 'process.tex', 'Linux Kernel Development Documentation',
'The kernel development community', 'manual'),
]
+
+todo_include_todos = True
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index 10aa692..acf13bb 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -55,3 +55,5 @@ lack of a better place.
=======
* :ref:`genindex`
+
+ .. todolist::
diff --git a/Documentation/security/conf.py b/Documentation/security/conf.py
index 472fc9a..78b30ab 100644
--- a/Documentation/security/conf.py
+++ b/Documentation/security/conf.py
@@ -6,3 +6,5 @@ latex_documents = [
('index', 'security.tex', project,
'The kernel development community', 'manual'),
]
+
+todo_include_todos = True
diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst
index 9bae6bb..b85944c 100644
--- a/Documentation/security/index.rst
+++ b/Documentation/security/index.rst
@@ -5,3 +5,12 @@ Security documentation
.. toctree::
tpm/index
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
+
+ .. todolist::
--
2.7.4