Message-ID: <20230828125912.hndmzfkof23zxpxl@tidings>
Date:   Mon, 28 Aug 2023 07:59:12 -0500
From:   Nishanth Menon <nm@...com>
To:     Jonathan Corbet <corbet@....net>
CC:     Mauro Carvalho Chehab <mchehab@...nel.org>,
        <linux-kernel@...r.kernel.org>, <linux-doc@...r.kernel.org>,
        <bpf@...r.kernel.org>,
        Heinrich Schuchardt <heinrich.schuchardt@...onical.com>,
        Mattijs Korpershoek <mkorpershoek@...libre.com>,
        Simon Glass <sjg@...omium.org>, Tom Rini <trini@...sulko.com>,
        Neha Francis <n-francis@...com>
Subject: Re: [PATCH 1/2] Documentation: sphinx: Add sphinx-prompt

Hi Jon,

On 16:46-20230825, Jonathan Corbet wrote:
> Nishanth Menon <nm@...com> writes:
> 
> > Sphinx-prompt[1] helps bring-in '.. prompt::' option that allows a
> > better rendered documentation, yet be able to copy paste without
> > picking up the prompt from the rendered documentation.
> >
> > [1] https://pypi.org/project/sphinx-prompt/
> > Link: https://lore.kernel.org/all/87fs48rgto.fsf@baylibre.com/
> > Suggested-by: Mattijs Korpershoek <mkorpershoek@...libre.com>
> > Suggested-by: Heinrich Schuchardt <heinrich.schuchardt@...onical.com>
> > Signed-off-by: Nishanth Menon <nm@...com>
> > ---
> > I would have added Reported-by for Simon, since he reported the issue in
> > the first place.. but it was for the u-boot documentation, so skipping
> > here.
> >
> >  Documentation/conf.py                 | 2 +-
> >  Documentation/sphinx/requirements.txt | 1 +
> >  2 files changed, 2 insertions(+), 1 deletion(-)
> 
> So it would sure be nice for the changelog to say what this actually
> does.

All this does is to bring in a better rendered documentation when
published in html format.
https://youtu.be/ItjdVa59jjE shows how the "copy-paste" functionality is
improved.

If you could recommend changes, I'd be glad to incorporate the same.

> 
> This appears to add a build dependency for the docs; we can't just add
> that without updating the documentation, adjusting
> scripts/sphinx-pre-install, and so on.

I had checked scripts/shinx-pre-install and that picks up
Documentation/sphinx/requirements.txt and installs the dependencies
from there using pip. Am I missing something?

Same thing with Documentation/doc-guide/sphinx.rst

Am I missing something?

> 
> But, beyond that, this extension goes entirely counter to the idea that
> the plain-text files are the primary form of documentation; it adds
> clutter and makes those files less readable.  We can do that when the

Are you sure this is going against the readable text documentation? If
anything it reduces the clutter and allows the text doc to be
copy-paste-able as well.

https://lore.kernel.org/all/20230824182107.3702766-3-nm@ti.com/

As you see from the diffstat:
 1 file changed, 10 insertions(+), 10 deletions(-)

Nothing extra added. What kind of clutter are you suggesting we added
with the change?

prompt:: bash $ is clearly readable that this is prompt documentation
in fact, dropping the "$" in the example logs, one can easily copy paste
the documentation from rst files as well.

> benefit is sufficient, but I'm pretty far from convinced that this is
> the case here.  Certainly the case hasn't been made in the changelog.
> What *is* the benefit of making this change?

Let me know *how* I can improve (note: I am not a native English
speaker, so, I'd appreciate any suggestions to make the argument clear
in the changelog). Intent here is to help make the rendered html
documentation that we publish in docs.kernel.org such as
https://docs.kernel.org/bpf/libbpf/libbpf_build.html better usable.


-- 
Regards,
Nishanth Menon
Key (0xDDB5849D1736249D) / Fingerprint: F8A2 8693 54EB 8232 17A3  1A34 DDB5 849D 1736 249D

Powered by blists - more mailing lists