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;
From:   Jonathan Corbet <corbet@lwn.net>
To:     Akira Yokosawa <akiyks@gmail.com>, linux-doc@vger.kernel.org
Cc:     Mauro Carvalho Chehab <mchehab@kernel.org>,
        "Maciej W. Rozycki" <macro@orcam.me.uk>,
        Miguel Ojeda <ojeda@kernel.org>, linux-kernel@vger.kernel.org,
        Akira Yokosawa <akiyks@gmail.com>
Subject: Re: [PATCH 2/5] docs/doc-guide: Mention make variable SPHINXDIRS
In-Reply-To: <ff89c064-e24a-0f2f-fc03-b029e5d04338@gmail.com>
References: <dccb5233-7f4f-1be6-d1f4-bbe9f42f88e0@gmail.com>
 <ff89c064-e24a-0f2f-fc03-b029e5d04338@gmail.com>
Date:   Thu, 09 Jun 2022 09:26:17 -0600
Message-ID: <87v8t9504m.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

Akira Yokosawa <akiyks@gmail.com> writes:

> SPHINXDIRS is useful when you want test builds of only those
> documents affected by your changes.
>
> Mention it in the "Sphinx Build" section.
>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Cc: Maciej W. Rozycki <macro@orcam.me.uk>
> ---
> This change is inspired from correspondence with Maciej [1].
>
> [1]: https://lore.kernel.org/r/f4d40da6-756b-9e75-b867-cc9eedc4b232@gmail.com
>
> --
>  Documentation/doc-guide/sphinx.rst | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
> index edc4fa023986..efcccab68286 100644
> --- a/Documentation/doc-guide/sphinx.rst
> +++ b/Documentation/doc-guide/sphinx.rst
> @@ -151,6 +151,10 @@ If the theme is not available, it will fall-back to the classic one.
>  
>  The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
>  
> +There is another make variable ``SPHINXDIRS``, which is useful when test
> +building a subset of documentation.  Again, see the documentation section
> +of ``make help`` for the details.

This should definitely be documented, it's kind of sad that we never did
that.  Rather than redirect readers to type a "make" command, though,
why not just tell them how to use it here?

Thanks,

jon