bpf.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Andrii Nakryiko <andrii.nakryiko@gmail.com>
To: Grant Seltzer Richman <grantseltzer@gmail.com>
Cc: bpf <bpf@vger.kernel.org>
Subject: Re: Generating libbpf API documentation
Date: Mon, 15 Mar 2021 17:47:24 -0700	[thread overview]
Message-ID: <CAEf4BzZy0XDYcchPkarUw5AusO7LZfOnswuOyUqakkVJ-ksCDQ@mail.gmail.com> (raw)
In-Reply-To: <CAO658oXG4HEm0rGEW-==0kaTmqenDUC_GM-qi7CEjwSakbnJRw@mail.gmail.com>

On Mon, Mar 15, 2021 at 9:51 AM Grant Seltzer Richman
<grantseltzer@gmail.com> wrote:
>
> Hi all,
>
> I have been experimenting with ways to contribute documentation to
> libbpf to make it easier for developers of bpf projects to use it.
> With the goal of making a documentation site that is easy to
> maintain/generate I found Doxygen (many of you may have experience
> with it, I did not). I set up a CI/CD workflow using github actions
> that runs doxygen on the libbpf mirror hosted there, and hosts the
> produced HTML using netlify. You can find the currently hosted version
> of it at https://libbpf-docs.netlify.app (I would gladly donate a real
> domain name for this purpose). The docs generation workflow is in my
> github repo here: https://github.com/grantseltzer/libbpf-docs

Thanks for investigating this! I've look at libbpf-docs.netlify.app,
and it seems like it just contains a list of structs and their fields
(both those that are part of libbpf API, as well as internal). Out of
all functions only two are listed there (libbpf_nla_parse_nested and
libbpf_nla_parse) and both are not part of libbpf API as well. So I
understand that I don't see any comments due to the '/**' format
(though it would be easy to run sed script adding it everywhere, just
as part of an experiment), but I'm not sure why none of API functions
are present there?

I think kernel docs used to be hosted on readthedocs.org, seems like
they are also providing hosting for open-source projects, so that
would solve the problem of the hosting. Have you looked at that
solution? It definitely has a bit more modern UI that
Doxygen-generated one :) but I don't know what are the real
differences between Sphinx and Doxygen and which one we should choose.

>
> In order to make this work all we would need is to format comments
> above functions we want to document. Doxygen requires that the comment
> just be in a block that starts with `/**`. I don't think doxygen
> specific directives should be committed to code but I think this is a
> fine convention to follow. Other doxygen directives (i.e. having
> `@file` in every file) can be faked using a step I have in the github
> actions.
>
> What does everyone think? Can we agree on this convention and start
> contributing documentation in this way? Any pitfalls to doxygen I'm
> not familiar with?
>
> Thanks!

  reply	other threads:[~2021-03-16  0:48 UTC|newest]

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-03-15 16:50 Generating libbpf API documentation Grant Seltzer Richman
2021-03-16  0:47 ` Andrii Nakryiko [this message]
2021-03-16 20:14   ` Grant Seltzer Richman
2021-04-16 19:38     ` Grant Seltzer Richman
2021-04-20  4:26       ` Andrii Nakryiko
2021-04-21 19:24         ` Grant Seltzer Richman
2021-04-22  3:58           ` Andrii Nakryiko
2021-04-22 21:20             ` Grant Seltzer Richman

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=CAEf4BzZy0XDYcchPkarUw5AusO7LZfOnswuOyUqakkVJ-ksCDQ@mail.gmail.com \
    --to=andrii.nakryiko@gmail.com \
    --cc=bpf@vger.kernel.org \
    --cc=grantseltzer@gmail.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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).