Skip to content

API documentation content organisation #630

Closed
Closed
API documentation content organisation#630
Labels
technicalTechnical issues on the website

Description

@fsimonis
fsimonis
opened on Oct 31, 2025

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

Activity

  1. fsimonis
    added a parent issue on Oct 31, 2025

  2. MakisH commented on Nov 5, 2025

    @MakisH
    MakisH
    on Nov 5, 2025
    Member

    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.

  3. MakisH commented on Nov 8, 2025

    @MakisH
    MakisH
    on Nov 8, 2025
    Member

    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.

  4. MakisH
    added
    technicalTechnical issues on the website
    on Dec 16, 2025

  5. fsimonis commented on Jan 22, 2026

    @fsimonis
    fsimonis
    on Jan 22, 2026
    MemberAuthor

    I found a rust project which can generate documentation for native building without building the native part.

    https://github.com/maplibre/maplibre-native-rs/blob/main/build.rs#L287-L294

    This is for docs.rs

  6. fsimonis commented on Feb 11, 2026

    @fsimonis
    fsimonis
    on Feb 11, 2026
    MemberAuthor

    Summary of questions:

    • Are we using language native documentation such as readthedocs for python and docs.rs for rust and link them from our website, or are we integrating them into our api website?
    • Do use a different subdomain for the API docs api.precice.org or deploy it as part of the main website precice.org/api.
    • How do we organize versions? Only latest and dev (can be built in one pipeline) or real versioning (may require to rebuild or safe for longer time)? If we remove the hotfix part of the version, then we can group all bindings versions together? 
      api.precice.org/latest/
api.precice.org/dev[elop[ment]]/
api.precice.org/3.3/
    • How do we organize languages? Currently, C++/C/Fortran are combined in a single Doxygen site. A welcome page could solve this confusion. 
      api.precice.org/latest/core/ << ?
api.precice.org/latest/python/
api.precice.org/latest/rust/
    • Do we group by language or by version? 
      api.precice.org/latest/python/
api.precice.org/dev/python/

api.precice.org/python/latest/
api.precice.org/python/dev/

  7. MakisH commented on Feb 17, 2026

    @MakisH
    MakisH
    on Feb 17, 2026
    Member

    Decisions from the coding days:

    • We use a subdomain: api.precice.org, to not mix with the website infrastructure
    • Languages first: api.precice.org/cpp, api.precice.org/c, api.precice.org/python
    • api.precice.org/c redirects to latest release preciceC.h page. This way, we can in the future move these links without breaking anything.
    • versions come next, no version means latest
    • We still include the development version, use the branch name: api.precice.org/cpp/develop/.

  8. MakisH commented on Mar 24, 2026

    @MakisH
    MakisH
    on Mar 24, 2026
    Member

    Updates:

    At the same time:

    I think that this issue is now complete. Related follow-ups:

  9. MakisH
    closed this as completedon Mar 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    technicalTechnical issues on the website

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions