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 <[email protected]>
---
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/[email protected]/
- 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
On Wed, Dec 7, 2022 at 10:03 AM 'David Gow' via KUnit Development
<[email protected]> wrote:
>
> 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 <[email protected]>
> ---
>
> 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/[email protected]/
> - 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.
>
This still looks good to me, thanks!
Reviewed-by: Sadiya Kazi <[email protected]>
> ---
> 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
>
> --
> 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 [email protected].
> To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/20221207043319.1890954-1-davidgow%40google.com.
On Wed, Dec 07, 2022 at 12:33:19PM +0800, David Gow wrote:
> 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 <[email protected]>
> ---
>
> 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/[email protected]/
> - 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
> +
Much better, thanks!
Reviewed-by: Bagas Sanjaya <[email protected]>
--
An old man doll... just what I always wanted! - Clara