[PATCH 0/3] documentation related updates

[PATCH 0/3] documentation related updates

[Luc Van Oostenryck]

Fix the doc generation with recent version of Sphinx,
fix the warnings in the doc generation and update the TODO.

Luc Van Oostenryck (3):
  doc: do not use obsolete sphinx.ext.autodoc.AutodocReporter
  doc: fix the warnings when building the doc
  doc: remove done item from the TODO

 Documentation/TODO.md              | 12 +++++------
 Documentation/nocast-vs-bitwise.md | 34 ++++++++++++++++--------------
 Documentation/sphinx/cdoc.py       | 10 ++++-----
 3 files changed, 28 insertions(+), 28 deletions(-)


base-commit: b8fad4bcd02210912de8cbdefcd77e9ca743a575
-- 
2.26.2

[PATCH 1/3] doc: do not use obsolete sphinx.ext.autodoc.AutodocReporter

[Luc Van Oostenryck]

sphinx.ext.autodoc.AutodocReporter is obsolete since Sphinx 1.7
and removed in some later versions.

So, replace it by the code suggested in the release notes when
it was obsoleted.

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
---
 Documentation/sphinx/cdoc.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/sphinx/cdoc.py b/Documentation/sphinx/cdoc.py
index 318e9b23626e..73c128cb7b35 100755
--- a/Documentation/sphinx/cdoc.py
+++ b/Documentation/sphinx/cdoc.py
@@ -269,7 +269,7 @@ if __name__ == '__main__':
 	dump_doc(extract(sys.stdin, '<stdin>'))
 
 
-from sphinx.ext.autodoc import AutodocReporter
+from sphinx.util.docutils import switch_source_input
 import docutils
 import os
 class CDocDirective(docutils.parsers.rst.Directive):
@@ -294,13 +294,13 @@ class CDocDirective(docutils.parsers.rst.Directive):
 
 		## let parse this new reST content
 		memo = self.state.memo
-		save = memo.reporter, memo.title_styles, memo.section_level
-		memo.reporter = AutodocReporter(lst, memo.reporter)
+		save = memo.title_styles, memo.section_level
 		node = docutils.nodes.section()
 		try:
-			self.state.nested_parse(lst, 0, node, match_titles=1)
+			with switch_source_input(self.state, lst):
+				self.state.nested_parse(lst, 0, node, match_titles=1)
 		finally:
-			memo.reporter, memo.title_styles, memo.section_level = save
+			memo.title_styles, memo.section_level = save
 		return node.children
 
 def setup(app):
-- 
2.26.2

[PATCH 2/3] doc: fix the warnings when building the doc

[Luc Van Oostenryck]

It seems that Markdown is now parsed slightly differently and
now generate some warnings.

So tweak the .md files to shut up the warnings.

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
---
 Documentation/TODO.md              |  6 +++++-
 Documentation/nocast-vs-bitwise.md | 34 ++++++++++++++++--------------
 2 files changed, 23 insertions(+), 17 deletions(-)

diff --git a/Documentation/TODO.md b/Documentation/TODO.md
index cbda1c397e46..31826df33aae 100644
--- a/Documentation/TODO.md
+++ b/Documentation/TODO.md
@@ -32,7 +32,7 @@ Core
   ```
 
 Testsuite
---------
+---------
 * there are more than 50 failing tests. They should be fixed
   (but most are non-trivial to fix).
 
@@ -84,9 +84,13 @@ Longer term/to investigate
 * should support "-Werror=..." ?
 * All warning messages should include the option how to disable it.
   For example:
+
   	"warning: Variable length array is used."
+
   should be something like:
+
 	"warning: Variable length array is used. (-Wno-vla)"
+
 * ptrlists must have elements be removed while being iterated but this
   is hard to insure it is not done.
 * having 'struct symbol' used to represent symbols *and* types is
diff --git a/Documentation/nocast-vs-bitwise.md b/Documentation/nocast-vs-bitwise.md
index b649abcd5947..9ba5a789fc26 100644
--- a/Documentation/nocast-vs-bitwise.md
+++ b/Documentation/nocast-vs-bitwise.md
@@ -1,4 +1,5 @@
-# __nocast vs __bitwise
+__nocast vs __bitwise
+=====================
 
 `__nocast` warns about explicit or implicit casting to different types.
 HOWEVER, it doesn't consider two 32-bit integers to be different
@@ -16,25 +17,26 @@ harder to lose the type by mistake.
 
 So the basic rule is:
 
- - `__nocast` on its own tends to be more useful for *big* integers
-that still need to act like integers, but you want to make it much
-less likely that they get truncated by mistake. So a 64-bit integer
-that you don't want to mistakenly/silently be returned as `int`, for
-example. But they mix well with random integer types, so you can add
-to them etc without using anything special. However, that mixing also
-means that the `__nocast` really gets lost fairly easily.
-
- - `__bitwise` is for *unique types* that cannot be mixed with other
-types, and that you'd never want to just use as a random integer (the
-integer `0` is special, though, and gets silently accepted - it's
-kind of like `NULL` for pointers). So `gfp_t` or the `safe endianness`
-types would be `__bitwise`: you can only operate on them by doing
-specific operations that know about *that* particular type.
+- `__nocast` on its own tends to be more useful for *big* integers
+  that still need to act like integers, but you want to make it much
+  less likely that they get truncated by mistake. So a 64-bit integer
+  that you don't want to mistakenly/silently be returned as `int`, for
+  example. But they mix well with random integer types, so you can add
+  to them etc without using anything special. However, that mixing also
+  means that the `__nocast` really gets lost fairly easily.
+
+- `__bitwise` is for *unique types* that cannot be mixed with other
+  types, and that you'd never want to just use as a random integer (the
+  integer `0` is special, though, and gets silently accepted - it's
+  kind of like `NULL` for pointers). So `gfp_t` or the `safe endianness`
+  types would be `__bitwise`: you can only operate on them by doing
+  specific operations that know about *that* particular type.
 
 Generally, you want `__bitwise` if you are looking for type safety.
 `__nocast` really is pretty weak.
 
-## Reference:
+Reference:
+----------
 
 * Linus' e-mail about `__nocast` vs `__bitwise`:
 
-- 
2.26.2

[PATCH 3/3] doc: remove done item from the TODO

[Luc Van Oostenryck]

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
---
 Documentation/TODO.md | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/Documentation/TODO.md b/Documentation/TODO.md
index 31826df33aae..4344a1dc9b0d 100644
--- a/Documentation/TODO.md
+++ b/Documentation/TODO.md
@@ -24,12 +24,6 @@ Core
   - add the sym into a list and
   - recalculate the addressability before memops's SSA conversion
 * bool_ctype should be split into internal 1-bit / external 8-bit
-* Previous declarations and the definition need to be merged. For example,
-  in the code here below, the function definition is **not** static:
-  ```
-	static void foo(void);
-	void foo(void) { ... }
-  ```
 
 Testsuite
 ---------
-- 
2.26.2