Docs: Move data types to Topics section

[mbercx]

Fixes #4449

There was still content from the previous documentation on data types that was missing from the revamped docs. Here we move this content into the "Topics - Data types" section.

Done

• Move all the content from the source/datatypes directory to the 'Data types' topics section, removing the source/datatypes directory afterwards.

• Restructure the content to first discuss the 'core' types, which we intend to keep in aiida-core in the long term, then the 'materials science' types, which may be moved to a plugin at some point. Move the export content to the end of the file.

• Reformat the content to the current style preferences:

  • Use one sentence per line.
  • Use the proper section headers.
  • Add the references in the proper format.
  • Switch to using the code-block directive instead of ::.

TODO

The section can still do with quite a large overhaul, I think. Some items on the TODO list:

• Write a short text for each data type, which can start from the "Aim" bullet point for each type.
• Move the other bullet points into a table, perhaps one for the "Core" and "Materials design" types each.
• Show some simple use cases (e.g. how to load a dictionary into a Dict node) for each of the data types.
• Test all of the KpointsData and BandsData examples. Consider removing legacy code.
• Consider moving "Export data nodes to various formats" content elsewhere:
  • Move the general text on the export method to the new "How to share data" section (Docs: How to share data #3998).
  • Move the data type specific information to the usage examples.
• Add redirects.

[giovannipizzi]

As you already mentioned, maybe all this section should be moved to an 'exporting data' section - like in "importing", we have two types (import an AiiDA DB, and import from external sources). Also here, we might want to have two types of export: export to AiiDA export file, and export to other formats (this section for the AiiDA data types).

[mbercx]

So far I have moved the CLI examples to the corresponding data type section (as they are rather specific) and kept the general description of the export() method at the end of the file. I suppose it could be fit into the "How to share data" section?

[giovannipizzi]

Yes, but I think we also discussed the option to just leave them at the bottom of the page in yesterday's meeting - I'm not sure which solution is better

[ramirezfranciscof]

@mbercx does this still require discussion or was this settled yesterday? If it does need discussion, let's remember to bring it up during today's meeting at 11.

[codecov]

Codecov Report

Merging #4469 into develop will decrease coverage by 0.19%.
The diff coverage is n/a.

@@             Coverage Diff             @@
##           develop    #4469      +/-   ##
===========================================
- Coverage    79.50%   79.31%   -0.18%     
===========================================
  Files          482      475       -7     
  Lines        35327    34840     -487     
===========================================
- Hits         28082    27631     -451     
+ Misses        7245     7209      -36     

Flag	Coverage Δ
django	73.16% <ø> (-0.50%)	⬇️
sqlalchemy	72.39% <ø> (-0.44%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
aiida/cmdline/commands/cmd_import.py	77.50% <0.00%> (-5.35%)	⬇️
aiida/cmdline/utils/echo.py	80.00% <0.00%> (-4.28%)	⬇️
aiida/cmdline/commands/cmd_export.py	90.45% <0.00%> (-3.57%)	⬇️
aiida/engine/daemon/runner.py	79.32% <0.00%> (-3.44%)	⬇️
aiida/engine/daemon/client.py	72.42% <0.00%> (-1.14%)	⬇️
aiida/tools/dbimporters/plugins/mpds.py	29.38% <0.00%> (-0.37%)	⬇️
aiida/tools/importexport/dbexport/__init__.py	97.72% <0.00%> (-0.36%)	⬇️
aiida/tools/importexport/dbimport/utils.py	82.90% <0.00%> (-0.22%)	⬇️
aiida/orm/nodes/data/cif.py	86.58% <0.00%> (-0.07%)	⬇️
aiida/common/log.py	95.53% <0.00%> (-0.06%)	⬇️
... and 51 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update eea2773...8f0fbd4. Read the comment docs.

[mbercx]

Thanks @giovannipizzi for the review! Besides your comments, I've already made a lot of changes to the previous version. I think the section is already in pretty good shape, but there are still some data types missing (CifData, OrbitalData and ProjectionData). However, since I still need to familiarize myself with these classes and their API before I can write their docs, this can still be quite time consuming. So either we:

• Continue with the content we have now so we can merge the PR asap, and open an issue to add the other data types in a next round of documentation days.
• Keep the PR open until I've added the discussion/examples of the other data types (but I'm not sure if I can manage that this week).

Let me know what you think is best! In case we want to merge it asap, I'll also look for another reviewer since you indicated you'd be busy today.

[chrisjsewell]

Before you merge this, please ensure that datatypes/index.rst is redirected to a suitable place (in docs/source/redirects.txt)

[mbercx]

@giovannipizzi this is ready for another round of review! Also fine to merge in its current state, I'll give the whole section another pass when adding the missing data types (#4529).

[giovannipizzi]

Thanks @mbercx ! A few comments to address, then it's ok to merge with me and the rest can be addressed in a future PR

[giovannipizzi]

yes

[giovannipizzi]

Thanks @mbercx !