Added most of the user documentation for the site
Added landing page, guide to select the right version of KUnit to use,
and Makefile rules to incorporate Linux kernel KUnit documentation.
Change-Id: Iaeabfd9265fb83086217d5d6858a4424edf65f27
Signed-off-by: Brendan Higgins <brendanhiggins@google.com>
diff --git a/.gitignore b/.gitignore
index 69fa449..3312038 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,3 @@
_build/
+third_party/kernel/_static/
+third_party/stable_kernel/_static/
diff --git a/Makefile b/Makefile
index 5e6f363..137bfd1 100644
--- a/Makefile
+++ b/Makefile
@@ -8,13 +8,54 @@
SOURCEDIR = .
BUILDDIR = _build
-# Put it first so that "make" without argument is like "make help".
-help:
- @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+# Put it first so that "make" without argument is like "make all".
+all: html
-.PHONY: help Makefile
+# param 1: The url of the git repo.
+# param 2: The branch to clone.
+# param 3: The directory to clone into.
+define git_clone_raw
+ git clone --depth 1 --single-branch $(1) --branch $(2) $(3)
+endef
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
- @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+# param 1: The url of the git repo.
+# param 2: The branch to clone.
+# param 3: The directory to clone into.
+define git_clone
+ if [ ! -d "$(3)" ]; then $(call git_clone_raw,$(1),$(2),$(3)); fi
+endef
+
+define mkdir
+ if [ ! -d "$(1)" ]; then mkdir $(1); fi
+endef
+
+# param 1: The url of the git repo.
+# param 2: The branch to clone.
+# param 3: The directory to clone into.
+# param 4: The name of the directory under third_party to copy the docs.
+# param 5: The directory under Documentation/ that contains the docs to copy.
+define fetch_kernel_docs
+ $(call git_clone,$(1),$(2),$(3))
+ make -C $(3) htmldocs SPHINXDIRS=$(5)
+ mkdir -p $(BUILDDIR)/html/third_party/$(4)
+ $(call mkdir,$(BUILDDIR)/html/third_party/$(4)/LICENSES/)
+ cp -r $(3)/LICENSES/* $(BUILDDIR)/html/third_party/$(4)/LICENSES/
+ $(call mkdir,$(BUILDDIR)/html/third_party/$(4)/docs/)
+ cp -r $(3)/Documentation/output/$(5)/* $(BUILDDIR)/html/third_party/$(4)/docs/
+endef
+
+fetch_stable_docs:
+ $(call fetch_kernel_docs,https://kunit.googlesource.com/linux,kunit/alpha/master,$(BUILDDIR)/stable_kunit,stable_kernel,test)
+
+fetch_upstream_docs:
+ $(call fetch_kernel_docs,https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git,next,$(BUILDDIR)/upstream_kunit,kernel,dev-tools/kunit)
+
+download_deps: fetch_stable_docs fetch_upstream_docs
+
+clean:
+ rm -rf $(BUILDDIR)
+
+.PHONY: all fetch_stable_docs fetch_upstream_docs download_deps clean html
+
+html: Makefile download_deps
+ @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/conf.py b/conf.py
index a6c8a1a..c9b54ae 100644
--- a/conf.py
+++ b/conf.py
@@ -101,7 +101,7 @@
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
diff --git a/development/index.rst b/development/index.rst
new file mode 100644
index 0000000..3ac14d2
--- /dev/null
+++ b/development/index.rst
@@ -0,0 +1,18 @@
+===========
+Development
+===========
+
+This set of pages provides information for developing KUnit itself. These pages
+are for you if you plan on making submissions to KUnit, you are using KUnit for
+really advanced use cases, or you just want to know more about how KUnit works
+under the hood.
+
+Checkout:
+
+.. TODO(brendanhiggins): add pages for each of these topics.
+
+- Getting Started for getting developing for KUnit.
+- Gerrit Workflow to see how you might structure your workflow to work with git and Gerrit.
+- KUnit Design to learn about how KUnit is organized and how it got here.
+- Useful Commands for a collection of tips and tricks while working on KUnit.
+- Release Processes on how to cut a release for KUnit.
diff --git a/index.rst b/index.rst
index 38f8933..55a8eb9 100644
--- a/index.rst
+++ b/index.rst
@@ -3,18 +3,101 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to KUnit's documentation!
-=================================
+=====
+KUnit
+=====
.. toctree::
:maxdepth: 2
:caption: Contents:
+ usage/index
+ development/index
+ third_party/kernel/index.rst
+ third_party/stable_kernel/index.rst
+What is KUnit?
+==============
-Indices and tables
+KUnit is a lightweight unit testing and mocking framework for the Linux kernel.
+These tests are able to be run locally on a developer’s workstation without a
+VM or special hardware.
+
+KUnit is heavily inspired by JUnit, Python's unittest.mock, and
+Googletest/Googlemock for C++. KUnit provides facilities for defining unit test
+cases, grouping related test cases into test suites, providing common
+infrastructure for running tests, mocking, spying, and much more. Get started
+now: :doc:`usage/index`
+
+Who is it for?
+==============
+
+If you work on the Linux kernel, then KUnit is for you.
+
+Why KUnit?
+==========
+
+Aside from KUnit there is no true unit testing framework for the Linux kernel.
+Autotest and kselftest (and within Google, Kokonut) are sometimes cited as unit
+testing frameworks; however, they are not by most reasonable definitions of
+unit tests.
+
+A unit test is supposed to test a single unit of code in isolation, hence the
+name. A unit test should be the finest granularity of testing and as such
+should allow all possible code paths to be tested in the code under test; this
+is only possible if the code under test is very small and does not have any
+external dependencies outside of the test's control like hardware.
+
+As far as I know, outside of KUnit, there are no testing frameworks currently
+available for the kernel that do not require installing the kernel on a test
+machine or in a VM and all require tests to be written in userspace running on
+the kernel; this is true for Autotest, kselftest, and Kokonut, disqualifying
+any of them from being considered unit testing frameworks.
+
+KUnit addresses the problem of being able to run tests without needing a
+virtual machine or actual hardware with User Mode Linux. User Mode Linux is a
+Linux architecture, like ARM or x86; however, unlike other architectures it
+compiles to a standalone program that can be run like any other program
+directly inside of a host operating system; to be clear, it does not require
+any virtualization support; it is just a regular program. User Mode Linux is
+fast: on my desktop it boots to init process in under a second.
+
+How do I use it?
+================
+
+- :doc:`usage/index` - for new users of KUnit
+- For upstream KUnit:
+ - `Usage <third_party/kernel/docs/usage.html>`__ - for a more detailed explanation of KUnit features
+ - `API <third_party/kernel/docs/api>`__ - for the list of KUnit APIs used for testing
+- For stable KUnit:
+ - `Usage <third_party/stable_kernel/docs/usage.html>`__ - for a more detailed explanation of KUnit features
+ - `API <third_party/stable_kernel/docs/api>`__ - for the list of KUnit APIs used for testing
+
+Where do I get it?
==================
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+- Upstream: https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/log/?h=next
+- Stable: https://kunit.googlesource.com/linux/+/kunit/alpha/master
+
+Not sure which one you want? Take a look at :doc:`usage/index`.
+
+Connect with us
+===============
+
+- Mailing List: kunit-dev@googlegroups.com
+- Google Groups (web interface for above): https://groups.google.com/forum/#!forum/kunit-dev
+- IRC: #kunit on oftc.net
+- Riot: `#kunit:matrix.org <https://riot.im/app/#/room/#_oftc_#kunit:matrix.org>`_
+
+Contributing
+============
+
+If you want to contribute to KUnit in the Linux kernel (which is just the same
+as contributing to the Linux kernel, please see `the Linux kernel's guide on
+contributing
+<https://www.kernel.org/doc/html/latest/#introduction-to-kernel-development>`_.
+
+For other KUnit repositories (CI/CD, vim plugin, etc), please see
+:download:`CONTRIBUTING.md <CONTRIBUTING.md>`.
+
+In all cases, you will also want to take a look at :doc:`development/index`.
diff --git a/third_party/kernel/index.rst b/third_party/kernel/index.rst
new file mode 100644
index 0000000..7d7169a
--- /dev/null
+++ b/third_party/kernel/index.rst
@@ -0,0 +1,17 @@
+================
+Upstream Version
+================
+
+Here we have a copy of the KUnit documentation taken from upstream.
+
+For convenience:
+
+Where to get the code
+---------------------
+
+https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/log/?h=next
+
+Getting Started Guide
+---------------------
+
+`docs/ <docs/>`_
diff --git a/third_party/stable_kernel/index.rst b/third_party/stable_kernel/index.rst
new file mode 100644
index 0000000..fab76f0
--- /dev/null
+++ b/third_party/stable_kernel/index.rst
@@ -0,0 +1,17 @@
+=================================
+Stable Version (aka Not Upstream)
+=================================
+
+Here we have a copy of the documentation taken from the stable branch of KUnit.
+
+For convenience:
+
+Where to get the code
+---------------------
+
+https://kunit.googlesource.com/linux/+/kunit/alpha/master
+
+Getting Started Guide
+---------------------
+
+`docs/ <docs/>`_
diff --git a/usage/index.rst b/usage/index.rst
new file mode 100644
index 0000000..5ee2dd7
--- /dev/null
+++ b/usage/index.rst
@@ -0,0 +1,90 @@
+===============
+Getting Started
+===============
+
+In order to use KUnit, you must first determine which branch you would like to
+use. What do we mean by that? We are in the process of upstreaming KUnit into
+the Linux kernel, so that means we have code under development that is not in
+the upstream repository or otherwise doesn't match what is currently upstream.
+
+For more information on why there are multiple versions of KUnit, see
+:ref:`why-multiple-versions`.
+
+For information on deciding which version you should use see
+:ref:`which-version`.
+
+.. _why-multiple-versions:
+
+Why are there multiple versions?
+================================
+
+Ideally, upstreaming code to the Linux kernel would be fast, we would be able to
+develope features entirely on LKML, no one would use code that had not yet been
+accepted upstream, and everything would have been done this way from the start.
+Unfortunately, we do not live in a perfect world, and consequently none of these
+are true.
+
+In short, we wrote a bunch of stuff to experiment with before we started sending
+things upstream, people started using that stuff, and upstream diverged. We made
+the decision that it is better to have 2 versions of KUnit rather than ``n``
+versions where ``n > 2``, so we decided to maintain a non-upstream branch called
+*stable* which has all the features not yet upstreamed, and would be maintained
+under the assumption that people are actually using it (hence, we don't make API
+breaking changes, or anything like that); this is why it's called *stable*. Our
+other branch is just upstream Linux.
+
+But wait, I see more than two branches!
+---------------------------------------
+
+For the upstream version, just use torvalds/master. Our *stable* branch is
+hosted at https://kunit.googlesource.com/linux/+/kunit/alpha/master.
+
+Nevertheless, you may notice that there are other branches hosted at
+https://kunit.googlesource.com/linux. All these branches are either based on
+upstream (and should not be used since they are not upstream yet), or are based
+on stable.
+
+.. _which-version:
+
+Which version should I use?
+===========================
+
+As for which branch you should use, upstream should be generally preferred (just
+as upstreaming your own code should be generally preferred); nevertheless, there
+are a lot of features that are not upstream yet, and will not be upstream for
+some time (possibly more than a year), if you need these features for your tests
+then you have no choice other than to use the stable branch.
+
+What features are available upstream?
+-------------------------------------
+
+- Basic test structure for defining test cases and test suites
+- Basic expectations and assertions
+- KUnit managed resources
+- Error reporting
+
+What features are not upstream yet?
+-----------------------------------
+
+- Class mocking
+- Function mocking
+- Hardware/platform faking
+- Error recovery
+
+Where to go
+===========
+
+Hopefully you now have a good idea whether you want to use the stable version,
+or the upstream version. As for where to go, see the following sections:
+
+Upstream Getting Started
+------------------------
+
+- Code: https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/log/?h=next
+- Documentation: :doc:`../third_party/kernel/index`
+
+Stable Getting Started
+----------------------
+
+- Code: https://kunit.googlesource.com/linux/+/kunit/alpha/master
+- Documentation: :doc:`../third_party/stable_kernel/index`
