search

NMRLipids / Databank

NMRlipids databank
GNU General Public License v3.0
4 stars 30 forks source link

Organizing and documenting API #141

Closed ohsOllila closed 6 months ago

ohsOllila commented 1 year ago

Inspired by the reviewer comments to the NMRlipids databank manuscript, I have started to organize the API, create documentation and make a better template for user analyses. Currently the plan is following:

  1. All the functions and classes will be moved to https://github.com/NMRLipids/Databank/blob/development/Scripts/BuildDatabank/databankLibrary.py. This can be then imported to the applications. Ideally, functions take the dictionary corresponding the simulation under analysis as an input, but in some cases input could be also something that can be easily extracted from the dictionary, such as ID number.
  2. Automatic document generation tool will be used to generate documentation of databankLibrary.py. This documentation can be then used as the manual of API. To exemplify this, I have created a documentation using pdoc3: https://htmlpreview.github.io/?https://github.com/NMRLipids/Databank/blob/development/Scripts/BuildDatabank/docs/databankLibrary.html
  3. There will be a separate template repository that can be used as a starting point when building new analyses. Such repository is already available in here: https://github.com/NMRLipids/databank-template/tree/main, and the template in here: https://github.com/NMRLipids/databank-template/blob/main/scripts/template.ipynb

I have already started to implement this in the development branch of the NMRlipids databank: https://github.com/NMRLipids/Databank/tree/development, and I will continue this with high priority.

The main focus is now to reply to reviewer comments by clarifying API to ease new analyses by all. Nevertheless, this organization will also support the improvements and clarifications in adding data and other parts which are already discussed in issue https://github.com/NMRLipids/Databank/issues/128 and addressed for example in this pull request https://github.com/NMRLipids/Databank/pull/140.

Comments and contributions are welcomed. Let's use this issue to coordinate and discuss this topic.

ohsOllila commented 1 year ago

The first version of documentation is now available at https://nmrlipids.github.io/

I am looking forward to hear comments on this.