openms / openms-docs Goto Github PK

Is your feature request related to a OpenMS Documentation problem? Please describe

No. Enhance UX and information for readers.

• I have attached screenshot describing the problem, if applicable

Describe the documentation enhancement you'd like

Add more screenshots in display-modes-and-view-options.md file.

Describe alternatives you've considered

NA.

Additional context

NA.

At the moment, the glossary term links are difficult to distinguish. By adding an image or changing the text colour, this will help them stand out.

We should change the default branch to develop from staging in sync with OpenMS/OpenMS.

User facing URLs:

• openms.readthedocs.io/en/develop
• openms.readthedocs.io/en/latest

URLs having redirects:

• openms.readthedocs.io/en/staging to openms.readthedocs.io/en/develop
• openms.readthedocs.io/en/test to openms.readthedocs.io/en/develop
• staging-openms.readthedocs.io/en/latest to openms.readthedocs.io/en/develop

Internal development URLs

• staging-openms.readthedocs.io/en/staging

Internal trial URLs

• staging-openms.readthedocs.io/en/test

Here are some examples containing the correct style for drop-down menu navigation:

The following needs to be changed to the style shown above (in this file):

Is your feature request related to a OpenMS API Reference Documentation? Please describe.

No, maintenance automation.

• I have attached screenshot describing the problem, if applicable.

Describe the documentation enhancement you'd like

Add automated link/URL check for broken or dead links.

Describe alternatives you've considered

This looks like a good GitHub action: https://github.com/marketplace/actions/markdown-link-check.

Additional context

Would you be interested in adding this GitHub action? @greengypsy

You can format keyboard strokes like so:
DEL
This should be added to the documentation.

This was discussed here.

For example:

Could be: A sequence of tools run on input data such as an mzML file which produces an output. There are over 185 TOPP tools to choose from.

Is your feature request related to a OpenMS Documentation problem? Please describe

No. UX.

• I have attached screenshot describing the problem, if applicable

Describe the documentation enhancement you'd like

Make the pages friendlier, especially beginner-friendly to make OpenMS more generic.

Describe alternatives you've considered

Icons: https://pradyunsg.me/furo/kitchen-sink/sphinx-design/#icons
Example: https://github.com/pradyunsg/furo/blob/main/docs/kitchen-sink/sphinx-design.md

To check code read the example page in RAW mode.

Additional context

None.

https://staging-openms.readthedocs.io/en/staging/docs/additional-resources/external-code-using-openms.html#shipping-external-code-to-a-new-machine

Ref: #65 (comment)

Is your feature request related to a OpenMS Documentation problem? Please describe

No. UI/UX enhancement.

• I have attached screenshot describing the problem, if applicable

Describe the documentation enhancement you'd like

Add a Twitter icon on the footer before RTD and GitHub icon:

Describe alternatives you've considered

How to do it in Furo: https://pradyunsg.me/furo/customisation/footer/.

Additional context

None.

As you can see, the bash lexer is not creating a token/span class separately for the command git:

We may need to modify the bash lexer using the instruction at the pygments website, in particular the "Modifying Token Streams" section.

I don't think this will be difficult to do, but I'm guessing is not high priority.

@jpfeuffer @tapaswenipathak would be good to hear your thoughts.

This issue tracks:

1. Movement of Doxygen pages to OpenMS-docs.
2. Movement of Wiki Pages to OpenMS API Reference, OpenMS-docs, and pyopenms-docs.
3. Addition of Tutorials to OpenMS-docs.
4. Addition of References in OpenMS-docs and updated information present in:
   • updateHMDB
   • usage_plots
   • dockerfiles
   • build-scripts
   • autowrap
   • contrib
   • PDCommunityNodes

Introduction should have a different, more detailed text.

Is your feature request related to a OpenMS API Reference Documentation? Please describe.

Would be nice if we used fixed version numbers in the docs, such that older docs still point to older releases in the install instructions.
This is only maintainable with variables. I bet this is easily possible with sphinx.

• I have attached screenshot describing the problem, if applicable.

Describe the documentation enhancement you'd like

Describe alternatives you've considered

Additional context

Is your feature request related to a OpenMS API Reference Documentation? Please describe.

No, UX.

• I have attached screenshot describing the problem, if applicable.

Describe the documentation enhancement you'd like

Use more keyboard keys for navigation.

Describe alternatives you've considered

Set the following to true:

• https://pradyunsg.me/furo/customisation/#navigation-with-keys
• navigation_with_keys

Additional context

NA.

Read Existing Documentation

I have checked the following places for the error:

• OpenMS Documentation Troubleshooting
• OpenMS API Developer FAQs

Create OpenMS Bug Report

I have created the bug report in OpenMS for any pipeline errors.

• OpenMS Open Issues

Description of the documentation bug

• I have attached screenshots of the incorrect documentation

Not all Glossary terms are assigned a term role.

If it is an .rst file. use :term:, otherwise use

{term}`glossary-term`

around the glossary term. All glossary terms are available here.

A few examples are below:

MS, MS/MS, TOPP, e.t.c.

Expected behaviour

All glossary terms should be linked to glossary definition.

OpenMS Installation

NA.

• Version:

Additional context

Plus points if this can be automated w/o false positives.

The following screenshot is from the user-interface.md file.

I think this text should go within a warning admonition. For more information on admonitions, see this link.

This is how I think the documentation could be structured:

Introduction

• What is OpenMS
• Background

Getting Started

• Installation on GNU/Linux
• Installation on macOS
• Installation on Windows

Quick Start Guides

• User Quick Start Guide
• Contributor Quick Start Guide

TOPP

• What is TOPP
• Key Concepts
• TOP tools
  • Graphical tools
  • File handling tools
  • Signal processing and preprocessing tools
  • Quanitation tools
  • Map Alignment tools
  • Protein/Peptide identification tools
  • etc

KNIME

• What is KNIME
• User interface
• Examples

TOPPAS

• What is TOPPAS
• User Interface
• Examples

Tutorials

• TOPP
• KNIME
• TOPPAS

Developer Resources

• Developer guidelines for adding new dependency libraries
• Link external code to OpenMS
• Custom compilation of OpenMS
• Build custom KNIME application
• Add new tool to the TOP suite

Additional Resources

• OpenMS git workflow
• Reporting bugs and issues
• Write and label github issues
• Pull request checklist

Downloads

• OpenMS installers
• Workflows
• OpenMS releases
• Other resources

Quick Reference

• Contributor FAQ
• Developer FAQ
• Glossary
• Contact Us

@tapaswenipathak @jpfeuffer would be great to hear your thoughts.

There are many places in the documentation, where back ticks are missing. Libraries, files and anything code related needs to be between back ticks. For example at this link:

This issue can be used as a tracker to close the point raised in the review of PR #65.

Is your feature request related to a OpenMS Documentation problem? Please describe

No, UX.

• I have attached screenshot describing the problem, if applicable

Describe the documentation enhancement you'd like

Describe alternatives you've considered

• how to do: https://pradyunsg.me/furo/customisation/announcement/.
• Link to OpenMS API reference documentation: https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/index.html
• If you want to fix/close this issue, you can also take reference from urllib3
• color code: #cccccc

Additional context

Connect OpenMS documentation with OpenMS API reference.

In the user quick start guide I think our definition of UTILS is a bit outdated. By now, we include experimental, little tested tools there as well.

Ref #65 (comment).

Check all occurrences of MacOS. Should be macOS imho

The current style of Notes etc does not look nice. There must be a wrong use of admonitions. Please check how to do this correctly.

Read Existing Documentation

I have checked the following places for the error:

• OpenMS Documentation Troubleshooting
• OpenMS API Developer FAQs

Create OpenMS Bug Report

I have created the bug report in OpenMS for any pipeline errors.

• OpenMS Open Issues

Description of the documentation bug

• I have attached screenshots of the incorrect documentation

Expected behaviour

OpenMS Installation

• Version:

Additional context

Is your feature request related to a OpenMS API Reference Documentation? Please describe.

No, cleanup.

• I have attached screenshot describing the problem, if applicable.

Describe the documentation enhancement you'd like

Right now, the lines are of varying lengths. Red vertical line is at 120 characters.

Describe alternatives you've considered

There should be some GitHub action, plugin, or something to automate this; if not, do it manually for consistency.

Additional context

I think OpenMS readthedocs requires a resync GitHub incoming webhook integration, I don't have the auth.

(tasks gets lost in discord, will use issues from now on)

It would be nice to add tooltips to glossary terms, so that people don't have to navigate away from the page to find a definition.

Resources include:

• https://sphinx-hoverxref.readthedocs.io/en/latest/usage.html#tooltip-on-glossary-terms
• https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#roles-an-in-line-extension-point
• https://sphinx-hoverxref.readthedocs.io/en/latest/configuration.html#confval-hoverxref_roles

For more info here is a link: https://www.w3schools.com/tags/tag_meta.asp

Basically it is for Search Engine Optimisation purposes. So I think we should have it.

But don't know how to implement it in markdown. We might need to write some sort of script. I'll keep digging if you think it's a good idea.

Read Existing Documentation

I have checked the following places for the error:

• OpenMS Documentation Troubleshooting
• OpenMS API Developer FAQs

Create OpenMS Bug Report

I have created the bug report in OpenMS for any pipeline errors.

• OpenMS Open Issues

Description of the documentation bug

• I have attached screenshots of the incorrect documentation

Glossary contents are not sorted, rn.

Expected behaviour

Sorted list.

OpenMS Installation

• Version:

Additional context

You can easily install openms via bioconda now on Linux and macOS.

Add that option.

Either to both subpages, or create an own page for it.

We should probably think about the order of the doc sections. I just looked at the headings in the Sidebar and I felt like the order is not always optimal. E.g. TOPP tools are explained after the TOPP Tutorial. And Scripting with TOPP might be better suited in the TOPP section.

Read Existing Documentation

I have checked the following places for the error:

• OpenMS Documentation Troubleshooting
• OpenMS API Developer FAQs

Create OpenMS Bug Report

I have created the bug report in OpenMS for any pipeline errors.

• OpenMS Open Issues

Description of the documentation bug

• I have attached screenshots of the incorrect documentation

Expected behaviour

OpenMS Installation

• Version:

Additional context

The images on the this page aren't rendering properly.

#65 (comment).

Ref:

• https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/UTILS_documentation.html
• 

The following extensions need to be tested:

Find more information here.

I think we should reorder. Not sure how stable our debian packages are. They should be moved down.
Docker instructions need update.

If you think it helps for UIX.

https://github.com/executablebooks/sphinx-tabs

For example: color or colour?

I have been using British spelling while I believe Tapasweni has been using American spelling.

Is your feature request related to a OpenMS Documentation problem? Please describe

No. UI/UX + automated user feedback for OpenMS Documentation.

• I have attached screenshot describing the problem, if applicable

Describe the documentation enhancement you'd like

Ask user if read page was helpful with yes or no.

Describe alternatives you've considered

How to Inject JS code documentation:

• https://pradyunsg.me/furo/customisation/injecting/
• https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html#adding-custom-css-or-javascript-to-sphinx-documentation
• https://pradyunsg.me/furo/kitchen-sink/sphinx-design/#buttons

Additional context

cc @greengypsy for suggesting the enhancement.

https://pygments.org/docs/lexers/#lexers-for-various-shells

currently the highlighting is off

We would like to create tutorials for TOPP shell and TOPPView.

The TOPP shell tutorial will explain how to set an input and manipulate the input data.

The TOPPView tutorial will explain how to visualise the data.

In order to do this we need:

• Some input data to provide to a user so that they can follow the instructions in the tutorial
• A few steps to manipulate this data
• More information about the images in the current file
• More information about spectrum and how to interpret a spectrum diagram

@tapaswenipathak feel free to add to this.

All URLs should be links. Or be given a named link. E.g. pkgs.org on Linux installation instructions

changes to be done: c4c8128.

https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/tutorial.html#tutorial_introduction