Where can I find the doxyfile?

Xin Wang napsal(a):

Hi,
I don't know where I can find the doxyfile which generate
"doxygen.postgresql.org" web site. I found that when reading code the
doxygen source code is quite helpful. However, I want to generate an
off-line copy of doxygen docs myself, but I can't find the doxyfile in
the lastest source release.

I think it is good idea. Stefan, what's about put it on the wiki?

Zdenek

Zdenek Kotala wrote:

Xin Wang napsal(a):

Hi,
I don't know where I can find the doxyfile which generate
"doxygen.postgresql.org" web site. I found that when reading code the
doxygen source code is quite helpful. However, I want to generate an
off-line copy of doxygen docs myself, but I can't find the doxyfile in
the lastest source release.

I think it is good idea. Stefan, what's about put it on the wiki?

don't think the wiki is a good place (we would have to maintain it in
addition to the main file) so I simply added a link on
http:/doxygen.postgresql.org that contains the current copy of the
configuration file that was used to generate a particular set of docs.
However some of the things there are specific to our install so a bit
(like some of the paths) of manual change will be required anyway.

Stefan

On 2008-06-02 18:33:42 Stefan Kaltenbrunner wrote:

Zdenek Kotala wrote:

Xin Wang napsal(a):

Hi,
I don't know where I can find the doxyfile which generate
"doxygen.postgresql.org" web site. I found that when reading code the
doxygen source code is quite helpful. However, I want to generate an
off-line copy of doxygen docs myself, but I can't find the doxyfile in
the lastest source release.

I think it is good idea. Stefan, what's about put it on the wiki?

don't think the wiki is a good place (we would have to maintain it in
addition to the main file) so I simply added a link on
http:/doxygen.postgresql.org that contains the current copy of the
configuration file that was used to generate a particular set of docs.
However some of the things there are specific to our install so a bit
(like some of the paths) of manual change will be required anyway.

Hello, sorry for resurrecting this old discussion, and necroposting,
but this was relevant.

It turns out that way back in 2008 it was possible to download Doxyfile
from https://doxygen.postgresql.org/ , which can be seen at:
https://web.archive.org/web/20080915132924/https://doxygen.postgresql.org/

I was able to download this Doxyfile from the web archive, and it actually
worked for me, after I changed the path to postgres sources and removed
header template. It even produced same result as on current web-site.

It would be nice if this doxygen file would be placed somewhere
on the current site.

P.S. I've tried to run doxygen on postgres sources without config,
and it didn't find any source file, this archived thread helped.

Perhaps doxygen file can be just placed into postgres git repository?

Best regards,
Bohdan Mart.

On Fri, Oct 6, 2023 at 10:50:25PM +0300, Bogdan Mart wrote:

On 2008-06-02 18:33:42 Stefan Kaltenbrunner wrote:

Zdenek Kotala wrote:

Xin Wang napsal(a):

Hi,
I don't know where I can find the doxyfile which generate
"doxygen.postgresql.org" web site. I found that when reading code the
doxygen source code is quite helpful. However, I want to generate an
off-line copy of doxygen docs myself, but I can't find the doxyfile in
the lastest source release.

I think it is good idea. Stefan, what's about put it on the wiki?

don't think the wiki is a good place (we would have to maintain it in
addition to the main file) so I simply added a link on
http:/doxygen.postgresql.org that contains the current copy of the
configuration file that was used to generate a particular set of docs.
However some of the things there are specific to our install so a bit
(like some of the paths) of manual change will be required anyway.

Hello, sorry for resurrecting this old discussion, and necroposting,
but this was relevant.

It turns out that way back in 2008 it was possible to download Doxyfile
from https://doxygen.postgresql.org/ , which can be seen at:
https://web.archive.org/web/20080915132924/https://doxygen.postgresql.org/

I was able to download this Doxyfile from the web archive, and it actually
worked for me, after I changed the path to postgres sources and removed
header template. It even produced same result as on current web-site.

It would be nice if this doxygen file would be placed somewhere
on the current site.

P.S. I've tried to run doxygen on postgres sources without config,
and it didn't find any source file, this archived thread helped.

Perhaps doxygen file can be just placed into postgres git repository?

We do link to a Doxygen build from our website:

https://www.postgresql.org/developer/coding/

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On 07.10.23 00:06, Bruce Momjian wrote:

On Fri, Oct 6, 2023 at 10:50:25PM +0300, Bogdan Mart wrote:

On 2008-06-02 18:33:42 Stefan Kaltenbrunner wrote:

Zdenek Kotala wrote:

Xin Wang napsal(a):

Hi,
I don't know where I can find the doxyfile which generate
"doxygen.postgresql.org" web site. I found that when reading code the
doxygen source code is quite helpful. However, I want to generate an
off-line copy of doxygen docs myself, but I can't find the doxyfile in
the lastest source release.

I think it is good idea. Stefan, what's about put it on the wiki?

don't think the wiki is a good place (we would have to maintain it in
addition to the main file) so I simply added a link on
http:/doxygen.postgresql.org that contains the current copy of the
configuration file that was used to generate a particular set of docs.
However some of the things there are specific to our install so a bit
(like some of the paths) of manual change will be required anyway.

Hello, sorry for resurrecting this old discussion, and necroposting,
but this was relevant.

It turns out that way back in 2008 it was possible to download Doxyfile
from https://doxygen.postgresql.org/ , which can be seen at:
https://web.archive.org/web/20080915132924/https://doxygen.postgresql.org/

I was able to download this Doxyfile from the web archive, and it actually
worked for me, after I changed the path to postgres sources and removed
header template. It even produced same result as on current web-site.

It would be nice if this doxygen file would be placed somewhere
on the current site.

P.S. I've tried to run doxygen on postgres sources without config,
and it didn't find any source file, this archived thread helped.

Perhaps doxygen file can be just placed into postgres git repository?

We do link to a Doxygen build from our website:

https://www.postgresql.org/developer/coding/

Yes, there is link to deployed documentation generated by Doxygen
(unless I'm missing something), but I am talking about config file
for Doxygen to generate same documentation locally.
There are no entries on Wiki regarding doxygen,
and not in build instructions.

I was able to locate needed config file in Web Archive:
https://web.archive.org/web/20081210081808if_/http://doxygen.postgresql.org:80/pgsql.conf

But it would be nice if it was readily available if anybody other would like
to build docs locally.

Sometime earlier, I created a filter to annotate regular C comments as doxy
comments. I'll attach it along with a sample doxyfile for running it. Just
in case it looks useful.

I've never been a big fan of Doxygen, but it seems to have gotten better
over time. Now that some IDEs display doxy comments on hover, I'm beginning
to appreciate it.

Sometime earlier, I created a filter to annotate regular C comments as doxy comments.
I'll attach it along with a sample doxyfile for running it. Just in case it looks useful.

I've never been a big fan of Doxygen, but it seems to have gotten better over time.
Now that some editors are displaying doxygen comments on hover, I'm beginning to appreciate it.

d

On 07.10.23 00:29, postgres@coyotebush.net wrote:

Sometime earlier, I created a filter to annotate regular C comments as doxy
comments. I'll attach it along with a sample doxyfile for running it. Just
in case it looks useful.

I've never been a big fan of Doxygen, but it seems to have gotten better
over time. Now that some IDEs display doxy comments on hover, I'm beginning
to appreciate it.

Thank you for providing this `flex` filter! It is actually useful. I've
tested it on one

file from postures source base, and it actually converted regular

comments to doc-comments! If this filter could be used by official

Doxygen generation of Postgres, it would highly increase quality

of online documentation of Postgres!

My initial idea was to create patches to upstream with changing comments

to documented comments, because current online dock is lacking comments,

but with this filter it would be unneeded, as documentation would be
able to

be generated from current sources!

To illustrate the point:

~~~~~~~~~~~

This function has Doxy style comment

```

src/interfaces/ecpg/compatlib/informix.c
672:/**
673- * initialize the struct, which holds the different forms
674- * of the long value
675- */
676-static int
677-initValue(long lng_val)

```

And it is rendered properly:

https://doxygen.postgresql.org/informix_8c.html#a0dad4c2ee52a831d3aa1bf1133e0e17d

But  function like this

```

src/backend/foreign/foreign.c

 /*
  * get_foreign_server_oid - given a server name, look up the OID
  *
  * If missing_ok is false, throw an error if name not found.  If true,
just
  * return InvalidOid.
  */
 Oid
 get_foreign_server_oid(const char *servername, bool missing_ok)

```

https://doxygen.postgresql.org/foreign_8c.html#a7959c56969be440c25b62c3c98ce2a78

doesn't have rendered documentation.

P.S. Was this original message from postgres@coyotebush.net intended to
be sent on John's Morris behalf?

On 07.10.23 00:23, Bohdan Mart wrote:

On 07.10.23 00:29, postgres@coyotebush.net wrote:

Sometime earlier, I created a filter to annotate regular C comments as
doxy
comments.  I'll attach it along with a sample doxyfile for running
it.  Just
in case it looks useful.

I've never been a big fan of Doxygen, but it seems to have gotten better
over time. Now that some IDEs display doxy comments on hover, I'm
beginning
to appreciate it.

Thank you for providing this `flex` filter! It is actually useful. I've
tested it on one

file from postures source base, and it actually converted regular

comments to doc-comments! If this filter could be used by official

Doxygen generation of Postgres, it would highly increase quality

of online documentation of Postgres!

I have not actually looked at the code of the filter itself but
personally I'm not super happy with doing a C-based filter as part of
our doxygen documentation generation step - that seems like an
additional maintainance burden infrastrukcture wise - is there nothing
more lightweight available(assuming we even want that)?

Stefan

On 09.10.23 11:38, Stefan Kaltenbrunner wrote:

I have not actually looked at the code of the filter itself but
personally I'm not super happy with doing a C-based filter as part of
our doxygen documentation generation step - that seems like an
additional maintainance burden infrastrukcture wise - is there nothing
more lightweight available(assuming we even want that)?

Hello, Stefan.

This indeed can require some maintenace, unfortunately. But I think it
is worth it! Please see screenshots in attachments. On the left there
are currently published doxygen, and on right is documentation I have
generated with John's config. (It doesn't show source, but I believe it
is discrepancy in config, not issue from filter).

There could be some false positive, like in this code:

/* Functions in access/index/amapi.c */
extern IndexAmRoutine *GetIndexAmRoutine(Oid amhandler);
extern IndexAmRoutine *GetIndexAmRoutineByAmId(Oid amoid, bool noerror);

Doxygen would concat `Functions in access/index/amapi.c` with actual
docs from .c file, and resulting docs would become:

GetIndexAmRoutine - call the specified access method handler routine to get its IndexAmRoutine struct, which will be palloc'd in the caller's context.

Functions in access/index/amapi.c.

Note that if the amhandler function is built-in, this will not involve any catalog access. It's therefore safe to use this while bootstrapping indexes for the system catalogs. relcache.c relies on that.

Definition at line 33 of file amapi.c.

But that's not big problem, IMHO. Better at least some docs misrendered,
than no comments in docs.

Other option would be to manually clean up documentation to provide more
concise comments. I can actually try doing it, few files at a time.
But that would damage git history and git-blame, unless we use
.git-blame-ignore-revs-entry

I have tested, and if we add such commit to ignoreblame, and don't
change actual line numbers, git-blame works fine.

So I have created draft patches(don't pay atention to commit message in
patch, it's just draft) with way, how this comemnts can be changed. It
can be done semi manually, with applying that filter by hands and then
commiting to git. I am willing to do that, if this option is preferable
over using filter during build process.

P.S. Editors, such as VsCode and CLion parses comments in any format and
show them as documentation, so if use standalone tool to view code
instead of Doxygen it is good experience. But having proper
documentation in Doxygen would help new people who haven't downloaded
code and configured IDE yet.

P.S. My original question was to have current doxygen config to be
published, like it was in 2008.

Regards,
Bohdan Mart.

Here’s a first pass at integrating that doxygen “C filter” into the meson build. As a prototype, it “seems to work”.

The command “ninja doxygen” generates html files under doc/doxygen/html.

On 12.10.23 09:07, John Morris wrote:

Here’s a first pass at integrating that doxygen “C filter” into the
meson build. As a prototype, it “seems to work”.

The command “ninja doxygen” generates html files under doc/doxygen/html.

Thanks. I have applied this patch and build (`ninja doxygen`) works.

But this Doxyfile don't generate dependency graph, which is present in
official doxygen, see screenshot-1.png.

Also it doesn't include sources from `contrib` dir.

I guess, @Stefan, we need original Doxyfile that is used to build
https://doxygen.postgresql.org/ currently.

I've also run it with ninja and no args, and observed following behavior:
* filter was compiled
* Doxyfile generated from template
* Doxygen generation didn't happen

I believe filter compilation and Doxygen generation shouldn't happen in
this case as well.

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

On 14.10.23 21:54, John Morris wrote:

Thank you for trying the patch out and commenting on it.

Thank you! I even didn't know such filters are possible, and after that
googling filter for C/C++ didn't gave good results.

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.

Yes, it shouldn't alter existing workflow.

* Provide options for other (non-html) output. (Which ones?)

I guess for now it is not needed, there were only HTML doxygen.

* Mention it in developer guidelines and provide sample code showing a
"desired" commenting style.

I think no changes are needed in guidelines at this point, just allow
existing comments to be collected.

In future some documentation from Doxygen style can be copied to
describe how to document function's parameter, etc.

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.

Yes, that's all I can think about at first stage, at least. Except last
bullet is too much. Better to not impose any new standards at this point.
Just get as much comments as possible from existing code-base.

And allow people build it locally.

Later on we can find problematic places where comments that should not
be pulled are pulled, and add some syntax into filter to exclude such
comments.

This are places, like section comments, like:
"all following fields are ***"

But at first step it's just good to have as much as possible comments
collected, even if some are misplaced.

So done is better than perfect.

----
Best regards,
Bohdan Mart.

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.

Here is an updated patch for generating Doxygen files from existing PostgreSQL source code.

* “ninja doxygen” builds Doxygen output under doc/doxygen/html.
* The C filter is only compiled when doxygen output is requested, and compiler warnings are now fixed.
* “meson configure -Ddoxygen_graphs=true” enables (caller,callee,include) graphs. Generating graphs is slow, so this feature is turned off by default.
* The output is closer to, but not yet identical to, https://doxygen.postgresql.org.
* As a personal preference, source code is not included inline in the documentation. Instead, it can be accessed by clicking a link.
* Added brief mention to the PostgreSQL guide on how to access or create Doxygen documentation.

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 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)

Rather than copying the Doxyfile, we could just publish the non-default values. As a mostly non-Doxygen user, I found it useful to see the config file in its entirety, but I agree it is a bit much.

Would only showing modified values make more sense?

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

Another update, this time with an abbreviated Doxyfile. Rather than including the full Doxyfile, this updated version only includes modified settings. It is more compact and more likely to survive across future doxygen versions.

* John Morris