| Message ID | 20221207043319.1890954-1-davidgow@google.com (mailing list archive) |
|---|---|
| State | New |
| Delegated to: | Brendan Higgins |
| Headers | show |
| Series | [v2] Documentation: kunit: Fix "How Do I Use This" / "Next Steps" sections | expand |
On Wed, Dec 7, 2022 at 10:03 AM 'David Gow' via KUnit Development <kunit-dev@googlegroups.com> 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 <davidgow@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.306449-1-davidgow@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. > This still looks good to me, thanks! Reviewed-by: Sadiya Kazi <sadiyakazi@google.com> > --- > 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 kunit-dev+unsubscribe@googlegroups.com. > 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 <davidgow@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.306449-1-davidgow@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 > + Much better, thanks! Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
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 +
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 <davidgow@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.306449-1-davidgow@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(-)