Drop or automate generating the API documentation

[oliverklee]

Continuing the document from #516 here.

I propose we either remove the PHPDoc API documentation at https://myintervals.github.io/PHP-CSS-Parser/ (and drop the corresponding Git branch and the Doxgen configuration file), or we automate generating the PHPDoc API docs so it stays in sync with the code. (As far as I can see, this is not automated yet.)

@JakeQZ wrote:

I don't know whether or how it's actively being used. However, having navigable HTML could still be useful in some situations:

• if the library was compiled into a PHAR, the PHPDoc wouldn't be available;
• when considering using the library, without having yet installed it, being able to browse the HTML documention could be helpful.

So I am not sure about removing this. Also, does keeping it cause any problem? I think it is should not exist in the package installed as a dependency via Composer (because it would just waste disk space there) - is that already taken care of?

May stance on this is:

• I don't find having the API documentation important.
• If we decide to keep it, I think we need to automate generating it so it's always in sync with the code.
• I'm not willing to put time into automating it, but would be fine with having the PHPDoc API docs if someone else put the time into automating it.
• I wouldn't be okay with keeping the API docs, but not keeping them up to date.

@sabberworm Do you know if and how much generating the PHPDoc API docs is already automated?

So these are the possible options I see:

a) drop it
b) automate it
c) keep it (and live with it getting outdated, or someone needs to manually regenerate it from time to time)

@sabberworm @JakeQZ Which of these options would you be okay with? And would you be willing to build the automation or taking over the responsiblity of re-generating the API docs every now and then?

[JakeQZ]

The Doxygen config file was added in 2014, but without any associated HTML output.

It does not appear to be actively used, and maybe never has been used to generate public-facing HTML documentation. I don't see any generated version of it anywhere.

I wouldn't be okay with keeping the API docs, but not keeping them up to date.

The change in #516 was just to remove the config file. I don't see any API docs anywhere. Maybe they were never added.

There is the readme, which needs to be kept up to date - as with all projects - but that appears to be hand-written (apart from the recently-added class diagram).

[sabberworm]

but without any associated HTML output.

What do you mean by that?

The docs are and always have been in the gh-pages branch, if that’s what you are referring to.

[JakeQZ]

but without any associated HTML output.

What do you mean by that?

The docs are and always have been in the gh-pages branch, if that’s what you are referring to.

Ah, I didn't know about the gh-pages branch.

[sabberworm]

I would be willing to spend some time to automate updating the gh-pages branch whenever we push to main.

[oliverklee]

Awesome! ❤️ I've created #522 for this.