API documentation content organisation

[fsimonis]

We want to integrate the documentation of the language bindings into the website.
A major question is how this should be organized. Currently, we :

• build the website
• build preCICE develop doxygen documentation
• build preCICE main/latest doxygen documentation
• move the doxygen docs to doxygen/main/ and doxygen/develop/
• add a page that links to these subpages

The downside of this approach is that everything needs to be built as part of the website CI and that there is currently no clear space for additional languages such as python or Fortran.

We need to rearrange where this is published.

Option 1: Unified website

Unify under precice.org/docs/api/<language>/[latest|develop].

• precice.org/docs/api/core/latest shows preCICE doxygen docs
• precice.org/docs/api/python/latest shows python docs
• precice.org/docs/api/rust/latest shows rust docs

Pro:

• Fits into the hugo migration (they can be moved/mounted into static/docs/api/...)
• Everything is part of a single deployment and thus a single workflow.
• This is easily extendable to other languages.
• Easier to fix the rendering infrastructure as it is all part of the website and doesn't need a new release.

Contra:

• Requires all language binding documentation to be built as part of the CI. Some of which require preCICE to be installed on the system.
• Fixes need to be done in the bindings repos and then updated in the website repo. (like tutorials)

Option 2: Separate websites

Deploy docs individually using GitHub pages then publish to subdomains:

• XX.precice.org show preCICE doxygen documentation
• python.precice.org or py.precice.org shows python docs
• rust.precice.org or rs.precice.org shows rust docs

Pro:

• Trivial to integrate with current website as clearly separated.
• Each repo can deploy its own documentation.
• Fixes of content are easier as they get directly pushed and published
• Subdomain separation looks very clean and easy to remember
• Easily extensible to other languages

Contra:

• Unclear what to call native docs (native.precice.org, api.precice.org, core.precice.org or cpp.precice.org all look weird). One could forward c.precice.org and fortran.precice.org to cpp.precice.org, but this requires extra repos with redirects.
• Unclear how to deploy latest and develop in separate folders.
• Creates a lot of extra off-topic commits due to the gh-pages branch in each binding repo.
• Fixes of infrastructure is more difficult as this may require a separate release to fix.
• Requires deployment workflow in each repo
• Clutters subdomains

[MakisH]

Good point, the current situation is indeed still a bit "work in progress" and unclear how to continue.

Which approach?

From the list of arguments, it sounds to me like option 1 (subdirectory) has clear benefits but no major disadvantages. I think it is also the generally expected location, and the [latest|develop] would be very handy.

It also better fits the concept of "all the documentation in one place", even if some feeling of integration would still need quite some additional effort.

Regarding the listed contra of option 1:

Requires all language binding documentation to be built as part of the CI. Some of which require preCICE to be installed on the system.

The main issue I see here is that a failure to build some bindings would block building the website. And since some of the bindings are currently less actively maintained, we might have an issue in even manually fixing the respective issues in reasonable time. See "middle way" below for a potential solution.

The CI jobs would also be longer, but this is not necessarily an issue. We could again use a prepared Docker image to make this faster.

Fixes need to be done in the bindings repos and then updated in the website repo. (like tutorials)

Do you mean that the changes will not be reflected on the website before the CI updates the submodules? For the frequency that this content is updated and consumed, I don't see an issue. We currently have a nightly update of the submodules, and we can trigger additional updates manually.

Middle way

Build artifacts

We could build the docs on each bindings repo and use it as a build artifact on the preCICE website. For this, we could use the download-artifact action, which allows downloading artifacts from other repositories.

This would split the responsibilities of building and of rendering and avoid blocking building issues: in case there is an issue with building the docs, the website can still be built.

Commits (less preferable)

As a less preferable, more simplistic approach (in case sharing artifacts is not an option), we could commit the output (ideally to Git LFS), and directly use it from the submodule. Having the generated docs already on each repository could also potentially be useful for developers for local rendering. We could even use pre-commit to update it with the respective commits. That would also act as a trigger to update any external documentation. Having it in LFS would keep the history a bit cleaner, given that this is generated (but still platform-independent) output.

But if sharing build artifacts works, I don't see a clear reason towards this direction.

Cross-linking

In any case, I think we should have prominent links back to the user documentation and the rest of the API languages on every page, so that when a user lands on the API pages coming from a search engine, they can easily discover more.

Ideally, as a user, I would like to also easily go to the same API method in another language.

[MakisH]

Interesting observation from another project:

Until v2112, OpenFOAM used subdirectories: https://www.openfoam.com/documentation/guides/latest/doc/

More recently, OpenFOAM uses subdomains: https://api.openfoam.com/2506/

I am not (yet) aware of the reasons to change, but I suspect the simplicity of maintenance, short URL, and to split the responsibilities of www.openfoam.com and api.openfoam.com among different teams/roles.