Migrate schema tutorial files from GitLab MR !2286 and update mkdocs …#7
Migrate schema tutorial files from GitLab MR !2286 and update mkdocs …#7
Conversation
hampusnasstrom
left a comment
hampusnasstrom
left a comment
There was a problem hiding this comment.
@siamakn I've gone through the first two pages for now and added my comments. I think we should discuss some things there before moving on.
mkdocs.yml
Outdated
| - Exploring data: tutorial/explore.md | ||
| - Access data via API: tutorial/access_api.md | ||
| - Schemas and plugins: tutorial/custom.md | ||
| - Schemas and plugins: |
There was a problem hiding this comment.
Not sure if this should really be called "Schemas and plugins" as we have another tutorial below on how to develop a plugin. What do you think?
|
@ahm531 this is the PR from Siamak that should be merged in under the ELN tutorial somehow. |
siamakn
force-pushed
the
5-rewrite-schema-tutorial-migrated-from-gitlab-2286
branch
from
a4cb44e to
f1f9ebd
Compare
| - Enable ELN functionality for manual data input and structured documentation. | ||
| - Extract structured data from files using parsers, which allow NOMAD to read data from raw files. | ||
| - Transform and enrich data post-upload using normalizers, ensuring compatibility with schema requirements and enhancing metadata consistency. | ||
| - Transform and enrich data, post-upload, using [normalizers](../../reference/glossary.md#normalizer), ensuring compatibility with schema requirements and enhancing metadata consistency. |
There was a problem hiding this comment.
But do you really mean a "normalizer" here? Aren't you referring to the normalize method of a schema?
siamakn
force-pushed
the
5-rewrite-schema-tutorial-migrated-from-gitlab-2286
branch
from
f1f9ebd to
115d571
Compare
|
|
Hi @yanghaoyu97@outlook.com @DanielYang59, I modified the The newly generated pages pages live under The previous test only looked for images filenames (assets in general) in md files located in the same directory level as the With this modification: for each Could you please confirm , or if you would prefer to keep the old behavior, I can revert this test changes. |
|
@DanielYang59 Thanks, Yes, it is exactly what I changed. |
|
Could you create a new branch and copy over the |
…ediate sub-directory then updated links to images
…ance clarity, update learning objectives, and improve structure.
…eriment, improve structure, and general revision
…ate example experiment details, and improve structure.
…ns, and making it consistent with the tutorials part of the docs
…r schema tutorials.
…ting the tabular parser section into an ELN template
There was a problem hiding this comment.
@siamakn Thank you very much! This is great work.
I have gone through the pages you have created and made several changes to improve consistency and clarity.
Main structural changes:
- Included the example admonitions for both in custom_eln_yaml.md and tabular_parser_yaml.md, to provide context of the scientific example used in the tutorials.
- “What you learn” come before “Before you Begin” - this was also corrected in the tutorials template. The Reasoning here is that the reader can first decide if it is something they are interested in reading, and then they evaluate if they can do it with the knowledge they have.
- Removed the section “A quick map of what your are building”. The path of the tutorial is provided concisely in the introductory part of each tutorial + the what you will learn. This paragraph is good and provides a more detailed and technical perspective of what will be done, however, I see the potential risk of introducing an overhead for the reader considering the technical terms not introduced.
For this reason, I would stick the general introduction paragraph provided. - Simplified the tasks when code is involved. The task in each step would to copy-paste a code snippet into a folder they are working with. This can be preceded with some introductory and concise statements, however, the “DO” task is to add the code to their schema file.
After this, clarification for the various elements is provided as bullet list (as complete as needed - precise - and concise as possible). - After each step, a checkpoint (admonition: success) is provided to show the current state of the file and to ensure that things are copied an pasted in the right place/indentation/order.
Content changes:
I have rewritten some parts to improve consistency with the other tutorials and provide more clarity while attempty stay concise.
Action requested:
The changes I made are in the recent commit to the PR. Please go through them once more, checking for typos, and any technical issues that I may have caused with me changes.
Please update the imagesin the sliders. - Update them so that the font is Titillium web (consistent with the other images in the tutorial)
- This applies for the image slider in step7 (both in custom_eln_yaml.md and tabular_parser_yaml.md)
5 participants
…config
Closes #56
Closes #5