All of lore.kernel.org
 help / color / mirror / Atom feed
From: Petr Mladek <pmladek@suse.com>
To: David Vernet <void@manifault.com>
Cc: linux-doc@vger.kernel.org, live-patching@vger.kernel.org,
	linux-kernel@vger.kernel.org, jpoimboe@redhat.com,
	jikos@kernel.org, mbenes@suse.cz, joe.lawrence@redhat.com,
	corbet@lwn.net, yhs@fb.com, songliubraving@fb.com
Subject: Re: [PATCH] Documentation: livepatch: Add kernel-doc link to klp_enable_patch
Date: Mon, 13 Dec 2021 17:06:09 +0100	[thread overview]
Message-ID: <YbdvcXKtxvrVqN+2@alley> (raw)
In-Reply-To: <YbObeiWbLxO8MwrD@dev0025.ash9.facebook.com>

On Fri 2021-12-10 10:24:58, David Vernet wrote:
> Petr Mladek <pmladek@suse.com> wrote on Fri [2021-Dec-10 10:25:05 +0100]:
> > 
> > Honestly, I do not like this. It might be acceptable when it converts
> > klp_enable_patch() into a link pointing to another page describing the API.
> > 
> > But this patch causes the entire documentation of klp_enable_patch()
> > inserted into livepatch.html. It does not fit there and breaks
> > the text flow.
> 
> Thank you for taking a look at the patch, Petr.
> 
> I'm happy to revise the patch to instead add a new `api.rst` file that
> contains the `kernel-doc` directive, which would cause `klp_enable_patch()`
> in `livepatch.rst` to automatically link to the separate page as you
> suggested.
> 
> Just to check though -- I see that `shadow-vars.rst` and `system-state.rst`
> have their own "API" sections.

Good point. Well, even these file do not point to the documentation
generated from the sources.


> Is it preferable to add such a section directly to `livepatch.rst`,
> rather than creating a separate file?

Good question. I am not expert on writing documentation and I can't
find any good example of API documentation at
https://www.kernel.org/doc/html/latest/index.html

One reason might be that most of the documentation was written as plain text
in the past. And many people still read it in the original .rst form.

Another problem is that livepatch documentation is a mix of several
independent pieces written by different authors. It would deserve
a lot of work:

    + Connect the pieces
    + Add missing information
    + Make the style and structure consistent


Anyway, I think that the documentation generated from the sources
is useful. But it is hard to integrate it into .rst file that should
be useful even in the .rst format.

From this POV, I suggest to create Documentation/livepatch/API.rst
and add there the documentation generated from the sources. I mean
something like:

    Documentation/core-api/kernel-api.rst

that results into

https://www.kernel.org/doc/html/latest/core-api/kernel-api.html


The livepatch/API.rst might include documentation from

    include/linux/livepatch.h
    kernel/livepatch/code.c
    kernel/livepatch/shadow.c
    kernel/livepatch/state.c


But let's wait if there are other opinions from another livepatch
developers.

Best Regards,
Petr

  reply	other threads:[~2021-12-13 16:06 UTC|newest]

Thread overview: 5+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-12-09 16:53 [PATCH] Documentation: livepatch: Add kernel-doc link to klp_enable_patch David Vernet
2021-12-10  9:25 ` Petr Mladek
2021-12-10 18:24   ` David Vernet
2021-12-13 16:06     ` Petr Mladek [this message]
2021-12-14  8:54       ` Miroslav Benes

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=YbdvcXKtxvrVqN+2@alley \
    --to=pmladek@suse.com \
    --cc=corbet@lwn.net \
    --cc=jikos@kernel.org \
    --cc=joe.lawrence@redhat.com \
    --cc=jpoimboe@redhat.com \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=live-patching@vger.kernel.org \
    --cc=mbenes@suse.cz \
    --cc=songliubraving@fb.com \
    --cc=void@manifault.com \
    --cc=yhs@fb.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.