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
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
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:
However, this is very bit confusing, since
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