search

nomad-coe / nomad

NOMAD lets you manage and share your materials science data in a way that makes it truly useful to you, your group, and the community.
https://nomad-lab.eu
Apache License 2.0
64 stars 14 forks source link

Python API reference #77

Open ericpre opened 11 months ago

ericpre commented 11 months ago

I couldn't find the python API reference in the documentation, did I miss it? This would be very useful to write python plugins (schema/parser), because at the moment, to know what class, argument can/should be used, I need to find relevant examples in the documentation, tutorial or existing plugins/parsers and this is tedious.

By the way, the python schema plugin capability is great, this is much more convenient to use than the yaml schema! :)

lauri-codes commented 11 months ago

Hi @ericpre!

You are right that our python API is not included in the documentation. Currently, the best way to understand the call signatures of functions is to explore the codebase with an IDE such as VSCode.

In principle, it should be easy to autogenerate such reference, but I think we are unsure how helpful this will be. Maybe we should at least document the core python API, so that it could be linked together with the how-to-guides..?

ericpre commented 11 months ago

What I am after is an overview of the classes expected to be used by plugins, how they related to each other and how they can used by plugins. There is already some narrative documentation but I suspect that if it were links to the API reference, it would much easier to get deeper understanding by navigating easily to the docstring when necessary. I find that a html version of the API is particularly useful to get familiar with the API because it is easier to navigate with the links, etc. and it give a good overview of the structure. Using docstrings from an IDE works and works well when you are looking for specific piece of information and you know where to look for it but it is tedious to use when not familiar with the API.

I don't know what is the core python API but I would happy with anything expected to be used by plugins! :)

lauri-codes commented 11 months ago

Ok, I see. I think one of the most important things to understand when writing plugins is the classes used to construct the schema. E.g. what are the classes that represent sections and quantities etc. This at least could be valuable to document.

I will try to see what I can do about this, and how I could connect this to our plugin how-to-guides.