[PATCH] Documentation: kunit: Fix "How Do I Use This" / "Next Steps" sections

[David Gow]

The 'index' and 'start' pages end with very similar "How Do I Use This"
/ "Next Steps" sections respectively, which link to the other
documentation pages. This wasn't updated when the tips.rst page was
removed.

Remove the reference to tips.rst, as well as tidy up the descriptions on
all of the links (especially given that sphinx gives the page titles
anyway.

Fixes: 4399c737a97d ("Documentation: kunit: Remove redundant 'tips.rst' page")
Signed-off-by: David Gow <davi...@google.com>
---
Documentation/dev-tools/kunit/index.rst | 18 +++++++-----------
Documentation/dev-tools/kunit/start.rst | 16 ++++++----------
2 files changed, 13 insertions(+), 21 deletions(-)

diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst
index d5629817cd72..beec6f847ef4 100644
--- a/Documentation/dev-tools/kunit/index.rst
+++ b/Documentation/dev-tools/kunit/index.rst
@@ -99,14 +99,10 @@ Read also :ref:`kinds-of-tests`.
How do I use it?
================

-* Documentation/dev-tools/kunit/start.rst - for KUnit new users.
-* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
-* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
-* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
-* Documentation/dev-tools/kunit/usage.rst - write tests.
-* Documentation/dev-tools/kunit/tips.rst - best practices with
- examples.
-* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
- used for testing.
-* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
- answers.
+* Documentation/dev-tools/kunit/start.rst - for new KUnit users
+* Documentation/dev-tools/kunit/architecture.rst - how KUnit is put together
+* Documentation/dev-tools/kunit/run_wrapper.rst - run tests via kunit.py
+* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit.py
+* Documentation/dev-tools/kunit/usage.rst - write tests
+* Documentation/dev-tools/kunit/api/index.rst - API reference
+* Documentation/dev-tools/kunit/faq.rst - common questions and answers
diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
index f4f504f1fb15..58c176348885 100644
--- a/Documentation/dev-tools/kunit/start.rst
+++ b/Documentation/dev-tools/kunit/start.rst
@@ -294,13 +294,9 @@ Congrats! You just wrote your first KUnit test.
Next Steps
==========

-* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
-* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
-* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
-* Documentation/dev-tools/kunit/usage.rst - write tests.
-* Documentation/dev-tools/kunit/tips.rst - best practices with
- examples.
-* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
- used for testing.
-* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
- answers.
+* Documentation/dev-tools/kunit/architecture.rst - how KUnit is put together
+* Documentation/dev-tools/kunit/run_wrapper.rst - run tests via kunit.py
+* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit.py
+* Documentation/dev-tools/kunit/usage.rst - write tests
+* Documentation/dev-tools/kunit/api/index.rst - API reference
+* Documentation/dev-tools/kunit/faq.rst - common questions and answers
--
2.38.1.584.g0f3c55d4c2-goog

[Sadiya Kazi]

Thank you David. This looks fine to me except for some very minor
suggestions below. Please feel free to ignore it if you do not agree.
Also, I can send out another patch to change the occurrences of
kunit_tool to kunit.py on run_wrapper.rst and run_manual.rst page to
maintain consistency across as they are referenced on index.rst and
start.rst.

Regards,
Sadiya

How about - start using KUnit

> +* Documentation/dev-tools/kunit/architecture.rst - how KUnit is put together

How about - get to know Kunit's design

> +* Documentation/dev-tools/kunit/run_wrapper.rst - run tests via kunit.py

How about - run tests with kunit.py

> +* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit.py

How about - run tests without kunit.py

> +* Documentation/dev-tools/kunit/usage.rst - write tests
> +* Documentation/dev-tools/kunit/api/index.rst - API reference
> +* Documentation/dev-tools/kunit/faq.rst - common questions and answers
> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
> index f4f504f1fb15..58c176348885 100644
> --- a/Documentation/dev-tools/kunit/start.rst
> +++ b/Documentation/dev-tools/kunit/start.rst
> @@ -294,13 +294,9 @@ Congrats! You just wrote your first KUnit test.
> Next Steps
> ==========
>
> -* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
> -* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
> -* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
> -* Documentation/dev-tools/kunit/usage.rst - write tests.
> -* Documentation/dev-tools/kunit/tips.rst - best practices with
> - examples.
> -* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
> - used for testing.
> -* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
> - answers.
> +* Documentation/dev-tools/kunit/architecture.rst - how KUnit is put together

same as above

> +* Documentation/dev-tools/kunit/run_wrapper.rst - run tests via kunit.py

same as above

> +* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit.py

same as above

[Bagas Sanjaya]

On 11/29/22 16:47, David Gow wrote:
> The 'index' and 'start' pages end with very similar "How Do I Use This"
> / "Next Steps" sections respectively, which link to the other
> documentation pages. This wasn't updated when the tips.rst page was
> removed.
>
> Remove the reference to tips.rst, as well as tidy up the descriptions on
> all of the links (especially given that sphinx gives the page titles
> anyway.
>

While this patch is LGTM, what about simply drop these sections and
replace with "see the sidebar for other KUnit documentations"?

--
An old man doll... just what I always wanted! - Clara

[Rae Moar]

On Tue, Nov 29, 2022 at 4:47 AM David Gow <davi...@google.com> wrote:
>
> The 'index' and 'start' pages end with very similar "How Do I Use This"
> / "Next Steps" sections respectively, which link to the other
> documentation pages. This wasn't updated when the tips.rst page was
> removed.
>
> Remove the reference to tips.rst, as well as tidy up the descriptions on
> all of the links (especially given that sphinx gives the page titles
> anyway.
>
> Fixes: 4399c737a97d ("Documentation: kunit: Remove redundant 'tips.rst' page")
> Signed-off-by: David Gow <davi...@google.com>

This all looks good to me and runs smoothly. I personally like to have
these links at the bottom of the page and think the new descriptions
are good. I commented on a few of them below.

Reviewed-by: Rae Moar <rm...@google.com>

> ---
> Documentation/dev-tools/kunit/index.rst | 18 +++++++-----------
> Documentation/dev-tools/kunit/start.rst | 16 ++++++----------
> 2 files changed, 13 insertions(+), 21 deletions(-)
>
> diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst
> index d5629817cd72..beec6f847ef4 100644
> --- a/Documentation/dev-tools/kunit/index.rst
> +++ b/Documentation/dev-tools/kunit/index.rst
> @@ -99,14 +99,10 @@ Read also :ref:`kinds-of-tests`.
> How do I use it?
> ================
>
> -* Documentation/dev-tools/kunit/start.rst - for KUnit new users.
> -* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
> -* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
> -* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
> -* Documentation/dev-tools/kunit/usage.rst - write tests.
> -* Documentation/dev-tools/kunit/tips.rst - best practices with
> - examples.
> -* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
> - used for testing.
> -* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
> - answers.
> +* Documentation/dev-tools/kunit/start.rst - for new KUnit users
> +* Documentation/dev-tools/kunit/architecture.rst - how KUnit is put together

I might slightly prefer Sadiya's version of this description: "get to
know KUnit's design." But I would be happy with either description.

> +* Documentation/dev-tools/kunit/run_wrapper.rst - run tests via kunit.py
> +* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit.py
> +* Documentation/dev-tools/kunit/usage.rst - write tests

I might slightly prefer "write KUnit tests" instead because with the
current description the line looks like:

Writing Tests - write tests

This seems a little repetitive, so "write KUnit tests" might be
slightly better. But this description is accurate and I would be fine
with it.

[David Gow]

The "How Do I Use This" section of index.rst and "Next Steps" section of
start.rst were just copies of the table of contents, and therefore
weren't really useful either when looking a sphinx generated output
(which already had the TOC visible) or when reading the source (where
it's just a list of files that ls could give you).

Instead, provide a small number of concrete next steps, and a bit more
description about what the pages contain.

This also removes the broken reference to 'tips.rst', which was
previously removed.

Fixes: 4399c737a97d ("Documentation: kunit: Remove redundant 'tips.rst' page")
Signed-off-by: David Gow <davi...@google.com>

---

Thanks everyone for reviewing v1. Since this is pretty much a complete
rewrite, I've left Reviewed-by tags off, as I don't feel the previous
reviews totally apply. Feel free to review again if you have any
comments.

Cheers,
-- David

Changes since v1:
https://lore.kernel.org/linux-kselftest/20221129094732.3...@google.com/
- Totally rewrite both sections to only include (and provide more
context for) the most concrete next steps.
- Thanks Bagas for pointing out that this basically duplicates the TOC
as-is.

---
Documentation/dev-tools/kunit/index.rst | 19 ++++++++-----------
Documentation/dev-tools/kunit/start.rst | 19 +++++++++----------
2 files changed, 17 insertions(+), 21 deletions(-)

diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst
index d5629817cd72..b3593ae29ace 100644
--- a/Documentation/dev-tools/kunit/index.rst
+++ b/Documentation/dev-tools/kunit/index.rst
@@ -99,14 +99,11 @@ Read also :ref:`kinds-of-tests`.

How do I use it?
================

-* Documentation/dev-tools/kunit/start.rst - for KUnit new users.
-* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
-* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
-* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
-* Documentation/dev-tools/kunit/usage.rst - write tests.
-* Documentation/dev-tools/kunit/tips.rst - best practices with
- examples.
-* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
- used for testing.
-* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
- answers.

+You can find a step-by-step guide to writing and running KUnit tests in
+Documentation/dev-tools/kunit/start.rst
+
+Alternatively, feel free to look through the rest of the KUnit documentation,
+or to experiment with tools/testing/kunit/kunit.py and the example test under
+lib/kunit/kunit-example-test.c
+
+Happy testing!
diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
index f4f504f1fb15..224387a43543 100644
--- a/Documentation/dev-tools/kunit/start.rst
+++ b/Documentation/dev-tools/kunit/start.rst
@@ -294,13 +294,12 @@ Congrats! You just wrote your first KUnit test.

Next Steps
==========

-* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
-* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
-* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
-* Documentation/dev-tools/kunit/usage.rst - write tests.
-* Documentation/dev-tools/kunit/tips.rst - best practices with
- examples.
-* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
- used for testing.
-* Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
- answers.

+If you're interested in using some of the more advanced features of kunit.py,
+take a look at Documentation/dev-tools/kunit/run_wrapper.rst
+
+If you'd like to run tests without using kunit.py, check out
+Documentation/dev-tools/kunit/run_manual.rst
+
+For more information on writing KUnit tests (including some common techniques
+for testing different things), see Documentation/dev-tools/kunit/usage.rst
+
--
2.39.0.rc0.267.gcb52ba06e7-goog

[Sadiya Kazi]

This still looks good to me, thanks!

Reviewed-by: Sadiya Kazi <sadiy...@google.com>

> --
> You received this message because you are subscribed to the Google Groups "KUnit Development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to kunit-dev+...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/20221207043319.1890954-1-davidgow%40google.com.

[Bagas Sanjaya]

Much better, thanks!

Reviewed-by: Bagas Sanjaya <bagas...@gmail.com>