Re: Including Doxyfile and Meson script for docs into main source tree - Mailing list pgsql-hackers

From: Stefan Kaltenbrunner <stefan@kaltenbrunner.cc>
Date: Thursday, November 2, 2023 at 2:51 AM
To: Bohdan Mart <mart.bogdan@gmail.com>
Cc: pgsql-hackers@postgresql.org <pgsql-hackers@postgresql.org>, 'Bruce Momjian' <bruce@momjian.us>, postgres@coyotebush.net <postgres@coyotebush.net>, John Morris <john.morris@crunchydata.com>
Subject: Re: Including Doxyfile and Meson script for docs into main source tree

Hi Bohdan!

I will see about making th ecurrent doxygen configuration available as a
download again in the next few days. Not sure whether there is an
additional actionable item yet as far as the project from John Morris
goes wrt. the postgresql.org sysadmin team.

The patch proposed is an enhancement of the build process in core
postgresql and I think we would look into utilizing that also for the
"official" build once applied.

I dont think we would want to locally maintain a C-based filter and a
custom build procedure otherwise.

On the patch itself I'm somewhat unconvinced that it is a good idea or
long-term maintainable to actually have a kinda random copy of the
configuration file(!) of an external software (doxygen in this) case in
our code that might need continous updating and maintainance to keep up
with new upstream releases.
As it stands the patch right now is against 1.9.4, with 1.9.1 running on
our installation and 1.9.8 being the latest release...


Stefan


On 30.10.23 14:57, Bohdan Mart wrote:
> Hello, Stefan!
>
> What do you think about this? See quoted message from John Morris.
>
> P.S. Also we would like you to provide currently used Doxyfile, as
> Postgres doxigen's home page no longer have link to download said file.
>
> Regards,
>      Bohdan.
>
> On 14.10.23 21:54, John Morris wrote:
>> Thank you for trying the patch out and commenting on it.
>>
>> I'm starting to think of it as a project. Here's a quick project
>> statement.
>>
>> The purpose is to generate improved  Doxygen output while making
>> maximal use of how Postgres currently does program comments.
>>
>> Thinking in terms of specific steps, and adding to what you have
>> mentioned:
>>
>>   * Configure Doxyfile so it produces output similar to previous output.
>>   * Only build Doxygen output if requested
>>   * Don't compile the filter or configure the Doxyfile  if they aren't
>>     needed
>>   * Include contrib in the sources to document
>>   * Provide options for other (non-html) output. (Which ones?)
>>   * Update Postgres documentation to include instructions for creating
>>     Doxygen output.
>>   * Mention it in developer guidelines and provide sample code showing a
>>     "desired" commenting style.
>>
>> Does that list seem complete? I don't want people to think we're
>> imposing new standards or legislating new commenting styles.  It's
>> more a matter of describing what we currently do, maybe with some
>> minor suggestions for improving.
>>
>>   * John Morris
>>