| Message ID | 20221129094732.306449-1-davidgow@google.com (mailing list archive) |
|---|---|
| State | New |
| Delegated to: | Brendan Higgins |
| Headers | show |
| Series | Documentation: kunit: Fix "How Do I Use This" / "Next Steps" sections | expand |
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 >
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"?
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 >
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
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(-)