Description
Description of the documentation bug
When developers want to install OpenMS (C++ lib + TOPP) from source on their local hardware, the installation instructions are a bit hard to find.
When you start from https://github.com/OpenMS/OpenMS-docs/blob/develop/docs/manual/develop/developer-faq.md?plain=1#L13 you end up on ReadTheDocs, and in particular
you might end up here: https://openms.readthedocs.io/en/latest/manual/develop.html (generated from https://github.com/OpenMS/OpenMS-docs/blob/develop/docs/manual/develop.md), which says
See the documentation for the [latest release](https://abibuilder.cs.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/index.html). but readers may simply miss that. It should explicitly say that these are the installation instructions to build OpenMS/TOPP from source!
... or
2) by a bit more clicking you end up here https://openms.readthedocs.io/en/latest/manual/develop/developer-faq.html (which is generated from https://github.com/OpenMS/OpenMS-docs/blob/develop/docs/manual/develop/developer-faq.md).
However, this page says:
....
Build OpenMS by following the installation instructions or [from source](https://github.com/OpenMS/OpenMS-docs/blob/develop/about/installation.rst).
...
However, this is very bit confusing, since
- the link to https://github.com/OpenMS/OpenMS-docs/blob/develop/about/installation.rst is meant for the installation of the precompiled binaries (i.e. no modification of source code is possible).
- The link to install from source should point to https://openms.de/current_doxygen/html/index.html (where the user can find instructions for Win, Mac and Linux)
- the binary installation pages for Win, Linux, Mac on ReadTheDocs, e.g. https://openms.readthedocs.io/en/latest/about/installation/installation-on-windows.html should make it explicitly clear that these are the precompiled binaries for users, not developers and should provide a link back to https://openms.readthedocs.io/en/latest/manual/develop/developer-faq.html for developers.
Note that links should not mention ReadTheDocs explicitly, but use internal references, e.g. see https://github.com/OpenMS/OpenMS-docs/blob/develop/docs/manual/develop/developer-faq.md?plain=1#L13 for the general idea.
Also, for external links to the Doxygen documentation, the link should point to https://openms.de/current_doxygen/... etc to make it more generic). In the past, we used links directly to https://abibuilder.cs.uni-tuebingen.de/archive/openms/Documentation/release/latest, which is essentially the same thing, but may change in the future).
OpenMS Installation
- Version: 3.3