git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: "Martin Ågren" <martin.agren@gmail.com>
To: Felipe Contreras <felipe.contreras@gmail.com>
Cc: Jeff King <peff@peff.net>,
	"brian m. carlson" <sandals@crustytoothpaste.net>,
	Bagas Sanjaya <bagasdotme@gmail.com>,
	Git Users <git@vger.kernel.org>
Subject: Re: [RFC suggestion] Generate manpage directly with Asciidoctor
Date: Mon, 10 May 2021 20:43:26 +0200	[thread overview]
Message-ID: <CAN0heSrcZrfD60SJW9pJADwF8=SQ3Zw0KW1ZZvF4EPh82cNtPw@mail.gmail.com> (raw)
In-Reply-To: <CAMP44s3wagd6pk-YfnYV3QoRbZ5cRA0MBU4=Mdxerbdx80J7hw@mail.gmail.com>

On Sun, 9 May 2021 at 20:46, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
>
> Are there some minimal requirements to say; this documentation was
> built correctly (as far as we know)? If so, maybe we can add a
> checker, or perhaps add a test under t/.

There's `make check-doc` which does some linting. But that's about
checking that there's a manpage at all for each builtin, that the doc
sources list sections in the right order, and such things. It doesn't
actually build the docs.

ci/test-documentation.sh runs `make check-doc` (see above), then goes on
to actually build the docs using both asciidoc and asciidoctor.  It
checks the exit status, but also that stderr is empty after filtering
out some expected, harmless output.

I think that's about the right balance. We could perhaps do something
under t/, but it probably shouldn't be to actually build the stuff. More
like, "oh, you've built the documentation -- let me sanity-check it for
you".  One way to detect that it makes sense to check it might be to see
if the Git version in the manpage footer(s) matches the version under
test. But I don't know what to check next.  (Actually, if we do find the
version number there, we have verified a fairly tricky piece of content
injection. At least "tricky" as in "we have more than one way of doing
it, because we support more than one toolchain" [1]. And if that stuff
broke, the test wouldn't notice, if we relied on detecting a version
match to even start testing...)

[1] See 7a30134358 ("asciidoctor-extensions: provide `<refmiscinfo/>`",
2019-09-16) and its parent commit.

Martin

  reply	other threads:[~2021-05-10 18:43 UTC|newest]

Thread overview: 38+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-07  6:06 Bagas Sanjaya
2021-05-07 12:02 ` Randall S. Becker
2021-05-07 22:55   ` Felipe Contreras
2021-05-07 22:57   ` brian m. carlson
2021-05-08  1:42     ` Randall S. Becker
2021-05-07 12:27 ` Đoàn Trần Công Danh
2021-05-07 12:47   ` Bagas Sanjaya
2021-05-07 23:03   ` Felipe Contreras
2021-05-08  4:27     ` Bagas Sanjaya
2021-05-07 20:25 ` brian m. carlson
2021-05-07 22:19   ` Jeff King
2021-05-08  4:22     ` Bagas Sanjaya
2021-05-09  8:20     ` Martin Ågren
2021-05-09 18:46       ` Felipe Contreras
2021-05-10 18:43         ` Martin Ågren [this message]
2021-05-10 22:24       ` Jeff King
2021-05-11  4:27         ` Felipe Contreras
2021-05-11  6:13           ` Jeff King
2021-05-11  8:03             ` Felipe Contreras
2021-05-11 12:44               ` Ævar Arnfjörð Bjarmason
2021-05-11 19:00                 ` Felipe Contreras
2021-05-11 19:09                   ` Jeff King
2021-05-11 20:22                     ` Felipe Contreras
2021-05-11 23:14           ` brian m. carlson
2021-05-12  1:44             ` Felipe Contreras
2021-05-11 18:45         ` Martin Ågren
2021-05-11 19:07           ` Jeff King
2021-05-11 19:11             ` Martin Ågren
2021-05-11 20:14             ` Felipe Contreras
2021-05-11  9:04       ` Jean-Noël Avila
2021-05-11 18:54         ` Martin Ågren
2021-05-07 23:35   ` Felipe Contreras
2021-05-07 23:57     ` brian m. carlson
2021-05-08  3:10       ` Jeff King
2021-05-08  3:23         ` Jeff King
2021-05-09  0:22         ` brian m. carlson
2021-05-09  8:29     ` Martin Ågren
2021-05-07 22:48 ` Felipe Contreras

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

  List information: http://vger.kernel.org/majordomo-info.html

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

  git send-email \
    --in-reply-to='CAN0heSrcZrfD60SJW9pJADwF8=SQ3Zw0KW1ZZvF4EPh82cNtPw@mail.gmail.com' \
    --to=martin.agren@gmail.com \
    --cc=bagasdotme@gmail.com \
    --cc=felipe.contreras@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=peff@peff.net \
    --cc=sandals@crustytoothpaste.net \
    --subject='Re: [RFC suggestion] Generate manpage directly with Asciidoctor' \
    /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

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

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 read-only IMAP folder(s) and NNTP newsgroup(s).