generate formats table in doc (#269)

* generate formats table in doc

Also fixes some typos

* bugfix

Author: njzjz

.gitignore

@@ -22,3 +22,6 @@ _version.py
 !tests/cp2k/aimd/cp2k.log
 !tests/cp2k/restart_aimd/ch4.log
 __pycache__
+docs/_build
+docs/formats.csv
+docs/api/

docs/conf.py

@@ -14,6 +14,7 @@
 #
 import os
 import sys
+import subprocess as sp
 from datetime import date
 sys.path.insert(0, os.path.abspath('..'))
 
@@ -171,8 +172,12 @@ def run_apidoc(_):
     module = os.path.join(cur_dir, "..", "dpdata")
     main(['-M', '--tocfile', 'api', '-H', 'API documentation', '-o', os.path.join(cur_dir, "api"), module, '--force'])
 
+def run_formats(_):
+    sp.check_output([sys.executable, "make_format.py"])
+
 def setup(app):
     app.connect('builder-inited', run_apidoc)
+    app.connect('builder-inited', run_formats)
 
 
 intersphinx_mapping = {

docs/formats.rst

@@ -0,0 +1,9 @@
+Supported Formats
+=================
+
+dpdata supports the following formats:
+
+.. csv-table:: Supported Formats
+   :file: formats.csv
+   :header-rows: 1
+

docs/index.rst

@@ -10,6 +10,7 @@ Welcome to dpdata's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   formats
    api/api
 
 .. mdinclude:: ../README.md

docs/make_format.py

@@ -0,0 +1,90 @@
+import csv
+from collections import defaultdict
+
+# ensure all plugins are loaded!
+import dpdata.plugins
+from dpdata.format import Format
+from dpdata.system import get_cls_name
+
+
+def get_formats() -> dict:
+    formats = defaultdict(list)
+    for kk, ff in Format.get_formats().items():
+        formats[ff].append(kk)
+    return formats
+
+def detect_overridden(cls: Format, method: str) -> bool:
+    """Check whether a method is override
+    
+    Parameters
+    ----------
+    cls : Format
+        a format
+    method : str
+        method name
+    
+    Returns
+    -------
+    bool
+        whether a method is overridden
+    """
+    return method in cls.__dict__
+
+def get_cls_link(cls: object) -> str:
+    """Returns class link.
+    
+    Parameters
+    ----------
+    cls : object
+        the class
+    
+    Returns
+    -------
+    str
+        the link of a class
+    """
+    return ':class:`%s <%s>`' % (cls.__name__, ".".join([cls.__module__, cls.__name__]))
+
+def check_supported(fmt: Format):
+    methods = set()
+    for mtd in [
+        'from_system', 'to_system',
+        'from_labeled_system', 'to_labeled_system',
+        'from_bond_order_system', 'to_bond_order_system',
+        'from_multi_systems', 'to_multi_systems',
+        ]:
+        if detect_overridden(fmt, mtd):
+            methods.add(mtd)
+            if mtd == 'to_system':
+                methods.add('to_labeled_system')
+    if fmt.MultiMode != fmt.MultiModes.NotImplemented:
+        methods.add('from_multi_systems')
+        methods.add('to_multi_systems')
+    return methods
+
+method_links = {
+    "from_system": ":func:`System() <dpdata.system.System>`",
+    "to_system": ":func:`System.to() <dpdata.system.System.to>`",
+    "from_labeled_system": ":func:`LabeledSystem() <dpdata.system.LabeledSystem>`",
+    "to_labeled_system": ":func:`LabeledSystem.to() <dpdata.system.System.to>`",
+    "from_bond_order_system": ":func:`BondOrderSystem() <dpdata.bond_order_system.BondOrderSystem>`",
+    "to_bond_order_system": ":func:`BondOrderSystem.to() <dpdata.system.System.to>`",
+    "from_multi_systems": ":func:`MultiSystems.load_systems_from_file() <dpdata.system.MultiSystems.load_systems_from_file>`",
+    "to_multi_systems": ":func:`MultiSystems.to() <dpdata.system.MultiSystems.to>`",
+}
+
+if __name__ == "__main__":
+    formats = get_formats()
+    with open('formats.csv', 'w', newline='') as csvfile:
+        fieldnames = [
+            'Class', 'Alias', 'Supported Functions',
+            ]
+        writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
+
+        writer.writeheader()
+        for kk, vv in formats.items():
+            writer.writerow({
+                'Class': get_cls_link(kk),
+                'Alias': '\n'.join(('``%s``' % vvv for vvv in vv)),
+                'Supported Functions': '\n'.join(method_links[mtd] for mtd in check_supported(kk)),
+            })

dpdata/plugins/deepmd.py

@@ -58,7 +58,7 @@ def from_labeled_system(self, file_name, type_map=None, **kwargs):
     MultiMode = Format.MultiModes.Directory
 
 @Format.register("deepmd/hdf5")
-class DeePMDCompFormat(Format):
+class DeePMDHDF5Format(Format):
     """HDF5 format for DeePMD-kit.
     
     Examples

dpdata/plugins/qe.py

@@ -27,7 +27,7 @@ def from_labeled_system(self, file_name, begin = 0, step = 1, **kwargs):
         return data
 
 @Format.register("qe/pw/scf")
-class QECPTrajFormat(Format):
+class QECPPWSCFFormat(Format):
     @Format.post("rot_lower_triangular")
     def from_labeled_system(self, file_name, **kwargs):
         data = {}

dpdata/plugins/siesta.py

@@ -34,7 +34,7 @@ def from_labeled_system(self, file_name, **kwargs):
 
 @Format.register("siesta/aimd_output")
 @Format.register_from("from_siesta_aiMD_output")
-class SiestaOutputFormat(Format):
+class SiestaAIMDOutputFormat(Format):
     def from_system(self, file_name, **kwargs):
         data = {}
         data['atom_names'], \

dpdata/system.py

@@ -139,7 +139,19 @@ def from_fmt_obj(self, fmtobj, file_name, **kwargs):
                     self.post_funcs.get_plugin(post_f)(self)
         return self
 
-    def to(self, fmt, *args, **kwargs):
+    def to(self, fmt: str, *args, **kwargs) -> 'System':
+        """Dump systems to the specific format.
+        
+        Parameters
+        ----------
+        fmt : str
+            format
+        
+        Returns
+        -------
+        System
+            self
+        """
         return self.to_fmt_obj(load_format(fmt), *args, **kwargs)
 
     def to_fmt_obj(self, fmtobj, *args, **kwargs):