Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Wed, 7 Dec 2022 15:58:28 +0700
From:   Bagas Sanjaya <bagasdotme@gmail.com>
To:     David Gow <davidgow@google.com>
Cc:     Shuah Khan <skhan@linuxfoundation.org>,
        Brendan Higgins <brendan.higgins@linux.dev>,
        Sadiya Kazi <sadiyakazi@google.com>,
        Rae Moar <rmoar@google.com>, Jonathan Corbet <corbet@lwn.net>,
        Daniel Latypov <dlatypov@google.com>,
        linux-kernel@vger.kernel.org, kunit-dev@googlegroups.com,
        linux-kselftest@vger.kernel.org, linux-doc@vger.kernel.org
Subject: Re: [PATCH v2] Documentation: kunit: Fix "How Do I Use This" / "Next
 Steps" sections
Message-ID: <Y5BVtHjnwpn5CFzf@debian.me>
References: <20221207043319.1890954-1-davidgow@google.com>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha256;
        protocol="application/pgp-signature"; boundary="gQZZMfvjrIhTAV6r"
Content-Disposition: inline
In-Reply-To: <20221207043319.1890954-1-davidgow@google.com>
Precedence: bulk


--gQZZMfvjrIhTAV6r
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

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).
>=20
> Instead, provide a small number of concrete next steps, and a bit more
> description about what the pages contain.
>=20
> This also removes the broken reference to 'tips.rst', which was
> previously removed.
>=20
> Fixes: 4399c737a97d ("Documentation: kunit: Remove redundant 'tips.rst' p=
age")
> Signed-off-by: David Gow <davidgow@google.com>
> ---
>=20
> 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.
>=20
> Cheers,
> -- David
>=20
> 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.
>=20
> ---
>  Documentation/dev-tools/kunit/index.rst | 19 ++++++++-----------
>  Documentation/dev-tools/kunit/start.rst | 19 +++++++++----------
>  2 files changed, 17 insertions(+), 21 deletions(-)
>=20
> 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?
>  =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> =20
> -*   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 kun=
it_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 documenta=
tion,
> +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
>  =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> =20
> -*   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 kun=
it_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 kuni=
t.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 techn=
iques
> +for testing different things), see Documentation/dev-tools/kunit/usage.r=
st
> +

Much better, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

--=20
An old man doll... just what I always wanted! - Clara

--gQZZMfvjrIhTAV6r
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iHUEABYIAB0WIQSSYQ6Cy7oyFNCHrUH2uYlJVVFOowUCY5BVrwAKCRD2uYlJVVFO
o90qAP0W0QiL12+wE0JzXPGrOMlc9sFK4uQuxOTzzy+QLsgflwEA+ZWGwB0Yy8f8
m2zrxJFPUg5QDxd6u2KAbBX0ztNinAg=
=m9er
-----END PGP SIGNATURE-----

--gQZZMfvjrIhTAV6r--