Move back API documentation to the main repository, update HTML export tooling

[nodiscc]

Followup to https://github.com/shaarli/Shaarli/pull/1997

Is there any reason why the api documentation is separated from the main documentation? It would be appreciable to have both at the same location

I'd also prefer it to be moved to the main repo. There is no actual reason other than (I guess) being able to use the https://shaarli.github.io/api-documentation/ URL on Github pages. I think that could be worked around easily (keep https://github.com/shaarli/api-documentation an empty repository, and have Shaarli's main repository CI push to the gh-pages branch there). Or maybe just regroup it with https://shaarli.readthedocs.io/?

Maintaining documentation across 2 repositories is painful and causes the API documentation repo to be neglected/forgotten about. We should try to find a way to move the API documentation back to https://github.com/shaarli/Shaarli/tree/master/doc, while keeping the HTML output on https://shaarli.github.io/api-documentation/

[nodiscc]

In addition:

and also to stop using aglio.js, as the last commit was in 2018

Actually the API documentation repo has been neglected since 2020, it still uses our old Travis CI account which stopped working about a year ago. I'm not sure the documentation itself is up to date, your PR to expose tags_separator just reminded me that this repo existed. As you noticed, the documentation renderer (aglio) is also unmaintained. We should move to another generator that supports the API blueprint source format.

[nodiscc]

We should move to another generator that supports the API blueprint source format.

The only remaining HTML renderers for the API blueprint format appear to be:

• https://github.com/SMillerDev/phpdraft/
• https://github.com/chris48s/django-apiblueprint-view
• https://github.com/funbox/blueprinter

[nodiscc]

https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/ - Sphinx domain for documenting HTTP APIs

[nodiscc]

• almost all API Blueprint renderers at https://apiblueprint.org/tools.html#renderers are unmaintained (including aglio)
• https://github.com/apiaryio/api-blueprint itself has not been touched since 2022 and there's no activity in issues, etc
• I made a few unsuccessful attempts to port the API documentation to our main sphinx-based documentation, using https://sphinxcontrib-httpdomain.readthedocs.io/ (which is also unmaintained) - the API documentation would not render properly, I guess because of interactions with the markdown parser (myst-parser)

Due to all this I'll unassign myself from this issue. The main problem IMHO is the API documentation repo being separated from the main repo, and the broken CI tooling (the HTML documentation is no longer updated when we commit to the API docs repo).

We need to carefully consider what our options are:

• Fix the api-documentation repo CI (switch from Travis to Github actions), and keep the repository separate
• Move the API documentation to the main repo, adapt our current GH Actions CI to build the HTML docs using aglio and push them to https://shaarli.github.io/api-documentation/
• Move the API documentation to the main repo, ditch aglio, and "manually" document the REST API on https://shaarli.readthedocs.io/en/master/REST-API.html. This appears to be the most sustainable solution although I kind of like the current API documentation look...

/cc @ArthurHoaro @virtualtam