doc: Adapt file names, index and content to in-kernel

Prepare for the in-kernel version of KTF where install instructions defer. Also adapt some sentences to the now have it both ways situation. Change-Id: I18833dfea25ded93d2def4384601d1f809c4b5bb Signed-off-by: Knut Omang <[email protected]> Reviewed-on: https://review.no.oracle.com:8443/c/ktf/+/16368 Pre-check: franklin <[email protected]> Reviewed-by: Alan Maguire <[email protected]>
alan-maguire · Aug 12, 2019 · 6824af2 · 6824af2
1 parent e5ce540
commit 6824af2
Show file tree

Hide file tree

Showing 11 changed files with 35 additions and 41 deletions.
diff --git a/doc/Makefile.am b/doc/Makefile.am
@@ -22,7 +22,7 @@ help:
 #
 htmldocs: $(TARGETS)
 
-$(TARGETS): Makefile $(srcdir)/*.txt
+$(TARGETS): Makefile $(srcdir)/*.rst
 	@if test x$V != x1; then export Q="-q"; echo -n "  HTMLDOC $$(pwd)"; fi; \
 	$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $$Q $(SPHINXOPTS) $(O) | \
 	if test x$V != x1; then grep -v 'Build finished'; else cat -; fi; \

diff --git a/doc/concepts.txt → doc/concepts.rst b/doc/concepts.txt → doc/concepts.rst
diff --git a/doc/debugging.txt → doc/debugging.rst b/doc/debugging.txt → doc/debugging.rst
diff --git a/doc/examples.txt → doc/examples.rst b/doc/examples.txt → doc/examples.rst
diff --git a/doc/features.txt → doc/features.rst b/doc/features.txt → doc/features.rst
diff --git a/doc/implementation.txt → doc/implementation.rst b/doc/implementation.txt → doc/implementation.rst
@@ -45,30 +45,26 @@ destination. For such tests you need to tell ktf (from user space) when the kern
 is going to be executed - this can happen multiple times depending on your test needs.
 Apart from that it works mostly like a normal gtest user level test.
 
-KTF as a separate git project
-*****************************
+Kernel integration of KTF or KTF as a separate git project?
+***********************************************************
 
-A lot of test infrastructure and utilities for the Linux kernel is implemented as part
-of the linux kernel git project. This has some obvious benefits, such as
+Yes. A lot of test infrastructure and utilities for the Linux kernel
+is implemented as part of the linux kernel git project.
+This has some obvious benefits, such as
 
 * Always being included
 * When APIs are changed, test code can be updated atomically with the rest of the kernel
-* Possible higher visibility and easier access
+* Higher visibility and easier access
 * Easier integration with internal kernel interfaces useful for testing.
 
-On the other hand keeping KTF as a separate project allows
+On the other hand providing KTF as a separate project allows
 
 * With some use of ``KERNEL_VERSION`` and ``LINUX_VERSION_CODE``, up-to-date KTF code and tests
   can be allowed to work across kernel versions.
-* This in turn allows newly developed tests to be tested on older kernels as well, possibly
+* This in turn allows a single set of newly developed tests to be
+  simultaneously tested against multiple older kernels, possibly
   detecting more bugs, or instances of bugs not backported.
-* User code can be integrated with the kernel code to be built with a single command
-* A smaller kernel git module and a more scalable development process where test related changes
-  does not to the same extent affect the core code history.
 
-Our current belief is that we would want integration of at least the kernel side of KTF,
-maybe just the ktf.ko kernel object, but that being able to maintain and build tests out-of-tree
-is an important feature that also need to be supported.
-
-We are open to suggestions from the community on whether whole or partial
-inclusion in the kernel tree or a separate project (or both...) is the best approach.
+So we will continue to support both, and have work in progress to simplify
+the maintenance and synchronization of the two versions, and allow the
+additional tooling to extend to KTF client test suites as well.
diff --git a/doc/index.rst b/doc/index.rst
@@ -0,0 +1,14 @@
+Kernel Test Framework documentation
+===================================
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   implementation
+   features
+   installation
+   concepts
+   examples
+   progref
+   debugging
diff --git a/doc/index.txt b/doc/index.txt
diff --git a/doc/installation.txt → doc/installation.rst b/doc/installation.txt → doc/installation.rst
@@ -48,7 +48,11 @@ KTF and your own test modules. Note that on some distros, cmake version
 2 and 3 comes as different packages, make sure you get version 3, which may
 require you to use ``cmake3`` as command instead of cmake above.
 
-To build KTF, cd to your source tree then clone the ktf project::
+Building the standalone version of KTF
+**************************************
+
+To build KTF from the standalone KTF git project,
+cd to your source tree then clone the ktf project::
 
 	cd ~/src
 	<clone ktf>

diff --git a/doc/introduction.txt → doc/introduction.rst b/doc/introduction.txt → doc/introduction.rst
@@ -79,10 +79,9 @@ impossible. This typically leads to bugs detected "down the road", when some new
 and starts using the API in a new way, or instabilities that go undetected because underlying
 semantics that the implementation implicitly depend upon changes in subtle ways.
 
-KTF can be compiled against existing kernels, and can use mechanisms such as KTF probes in cases
-where calls to other functions needs to be intercepted and/or modified to create the right test
-condition, whether it means waiting for a potential race condition to occur, or return an error
-value, or just collect state to make assertions.
+KTF can use mechanisms such as KTF probes in cases where calls to other functions needs to be
+intercepted and/or modified to create the right test condition, whether it means waiting for a
+potential race condition to occur, or return an error value, or just collect state to make assertions.
 
 Typical classical use cases that lend itself well to unit testing are simple APIs with a relativ
 complex implementation - such as container implementations. Typical kernel examples of these

diff --git a/doc/progref.txt → doc/progref.rst b/doc/progref.txt → doc/progref.rst