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

[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 <davidgow@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

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

[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


On Tue, Nov 29, 2022 at 3:17 PM David Gow <davidgow@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 <davidgow@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
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
> +*   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
>

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

[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

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

[Rae Moar]

On Tue, Nov 29, 2022 at 4:47 AM David Gow <davidgow@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 <davidgow@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 <rmoar@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.

> +*   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
>