Skip to contentSkip to conversation

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

PATCH In review David Gow 3 participants 3 messages Dec 7, 2022

Subsystems (4)
lore
Share & tools
lore

David Gow

author
#0 lore raw

PATCH v2 1/1 Documentation: kunit: Fix "How Do I Use This" / "Next Steps" sections

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")

---

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(-)
Documentation/dev-tools/kunit/index.rst +8 -11
index d5629817cd72..b3593ae29ace 100644
@@ -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!
Documentation/dev-tools/kunit/start.rst +9 -10
index f4f504f1fb15..224387a43543 100644
@@ -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
+
Signature · 1 line
2.39.0.rc0.267.gcb52ba06e7-goog
Reviewed-by on v2 1/1
#1 lore raw
Quoted 25 lines · David Gow' via KUnit Development

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")

---

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

Quoted 7 lines

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!

Quoted 66 lines
---
 Documentation/dev-tools/kunit/index.rst | 19 ++++++++-----------
 Documentation/dev-tools/kunit/start.rst | 19 +++++++++----------
 2 files changed, 17 insertions(+), 21 deletions(-)
Documentation/dev-tools/kunit/index.rst +8 -11
index d5629817cd72..b3593ae29ace 100644
@@ -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!
Documentation/dev-tools/kunit/start.rst +9 -11
index f4f504f1fb15..224387a43543 100644
@@ -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.

Reviewed-by on v2 1/1
#2 lore raw
In reply to David Gow
Quoted 80 lines · 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")

---

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(-)
Documentation/dev-tools/kunit/index.rst +8 -11
index d5629817cd72..b3593ae29ace 100644
@@ -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!
Documentation/dev-tools/kunit/start.rst +0 -9
index f4f504f1fb15..224387a43543 100644
@@ -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

Documentation/dev-tools/kunit/start.rst Congrats! You just wrote your first KUnit test. · line 305

Quoted 10 lines
Documentation/dev-tools/kunit/start.rst +9 -1
-    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!

Signature · 1 line
An old man doll... just what I always wanted! - Clara