Improved the doumentation

cimpy/examples.py

@@ -2,24 +2,32 @@ from pathlib import Path
 
 
 def import_example():
+    """TODO: Add documentation
+    """
     base = Path(__file__).resolve().parent.parent
     example = base / 'examples' / 'quickstart' / 'importCIGREMV.py'
     exec(open(example).read())
 
 
 def export_example():
+    """TODO: Add documentation
+    """
     base = Path(__file__).resolve().parent.parent
     example = base / 'examples' / 'quickstart' / 'exportCIGREMV.py'
     exec(open(example).read())
 
 
 def convertToBusBranch_example():
+    """TODO: Add documentation
+    """
     base = Path(__file__).resolve().parent.parent
     example = base / 'examples' / 'quickstart' / 'convertToBusBranch.py'
     exec(open(example).read())
 
 
 def addExternalNetworkInjection_example():
+    """TODO: Add documentation
+    """
     base = Path(__file__).resolve().parent.parent
     example = base / 'examples' / 'quickstart' / 'addExternalNetworkInjection.py'
     exec(open(example).read())

cimpy/utils.py

 import importlib
-import cimpy
-
 
 def node_breaker_to_bus_branch(import_result):
+    """TODO: Add documentation
+    """
     res = import_result['topology']
     breaker_list = []
     terminals_list = []
@@ -86,6 +86,8 @@ def node_breaker_to_bus_branch(import_result):
 
 
 def add_external_network_injection(import_result, version, mRID, voltage_set_point):
+    """TODO: Add documentation
+    """
     res = import_result['topology']
     TopologicalNode = ''
     if mRID in res:

documentation/Functions.rst

-Functions
-=========
-The CIMpy package contains two major functions, one function to import network data from XML/RDF files called cim_import and one function to export the network data back to XML/RDF files called cim_export. A description of both functions with their attributes can be found below.
-
-
-CIM Import
-""""""""""
-
-Function for creating CIMpy objects out of a CIM topology.
-
-.. code-block::
-
-   cimpy.cim_import(xml_files, cim_version, start_dict=None)
-
-Arguments:
-    :xml_files:      List of CIM RDF/XML files
-    :cim_version:    String containing the CGMES version
-
-Optional Arguments:
-    :start_dict:     List of CIM classes which should be read, default: read all classes
-
-Output:
-    :import_result:  A dictionary containing the topology and meta information. The topology can be extracted via
-                    import_result['topology']. The topology dictionary contains all CIMpy objects accessible via their mRID. The meta
-                    information can be extracted via import_result['meta_info']. The meta_info dictionary contains a new dictionary with
-                    the keys: 'author', 'namespaces' and 'urls'. The last two are also dictionaries. 'urls' contains a mapping
-                    between references to URLs and the extracted value of the URL, e.g. 'absoluteValue':
-                    'http://iec.ch/TC57/2012/CIM-schema-cim16#OperationalLimitDirectionKind.absoluteValue' These mappings are accessible
-                    via the name of the attribute, e.g. import_result['meta_info']['urls'}[attr_name] = {mapping like example above}.
-                    'namespaces' is a dictionary containing all RDF namespaces used in the imported xml files.
-
-
-CIM Export
-""""""""""
-
-Function for serialization of CIMpy objects to XML files.
-
-.. code-block::
-
-   cimpy.cim_export(import_result, file_name, version, acitiveProfileList):
-
-Arguments:
-   :import_result:      A dictionary containing the topology and meta information. The topology can be extracted via
-                        import_result['topology']. The topology dictionary contains all CIMpy objects accessible via their mRID. The meta
-                        information can be extracted via import_result['meta_info']. The meta_info dictionary contains a new dictionary with
-                        the keys: 'author', 'namespaces' and 'urls'. The last two are also dictionaries. 'urls' contains a mapping
-                        between references to URLs and the extracted value of the URL, e.g. 'absoluteValue':
-                        'http://iec.ch/TC57/2012/CIM-schema-cim16#OperationalLimitDirectionKind.absoluteValue' These mappings are accessible
-                        via the name of the attribute, e.g. import_result['meta_info']['urls'}[attr_name] = {mapping like example above}.
-                        'namespaces' is a dictionary containing all RDF namespaces used in the imported xml files.
-   :file_name:          String containing the name for the XML files.
-   :version:            String containing the CGMES version
-   :activeProfileList:  A list containing all profiles which are active for the export
-
-Output:
-    One XML file for each package in the CGMES version. The package name is added to the file name like [file_name]_[package].xml

documentation/Versions.rst

-CIM Class Documentation
-"""""""""""""""""""""""
-
-Currently only the CGMES version v2_4_15 is supported. An overview can be found  in the :ref:`modindex`. You can also use the search bar on the left.
-
-.. toctree::
-   :glob:
-   :maxdepth: 3
-
-   cimpy

documentation/cimpy.cgmes_v2_4_15.rst

+cimpy.cgmes\_v2\_4\_15 package
+==============================
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   cimpy.cgmes_v2_4_15.*
\ No newline at end of file

documentation/cimpy.rst

-cimpy package
-=============
+cimpy Package Documentation
+===========================
 
-Subpackages
------------
+cimpy consists of the following modules:
 
 .. toctree::
    :maxdepth: 1
-   :glob:
 
-   cimpy.*
-
-
-cimexport module
-----------------------
-
-.. automodule:: cimpy.cimexport
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-cimimport module
-----------------------
-
-.. automodule:: cimpy.cimimport
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-examples module
----------------------
-
-.. automodule:: cimpy.examples
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-utils module
-------------------
-
-.. automodule:: cimpy.utils
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: cimpy
-   :members:
-   :undoc-members:
-   :show-inheritance:
+   cimpy.cgmes_v2_4_15
+   cimpy.cimexport
+   cimpy.cimimport
+   cimpy.examples
+   cimpy.utils

documentation/docu.sh

 python3 ../setup.py develop
-sphinx-apidoc -F -H "cimpy" -o "../documentation" "../" "../setup.py"
+sphinx-apidoc -F -H "cimpy" --separate -o "../documentation" "../" "../setup.py"
 python3 set_inheritance_diagram.py
 cd ../documentation
 make html

documentation/index.rst

@@ -30,5 +30,4 @@ Contact
 
    Install
    Start
-   Functions
-   Versions
+   cimpy

documentation/set_inheritance_diagram.py

@@ -35,7 +35,7 @@ for file in os.listdir(directory):
                             new_file.write('\nInheritance Diagram:\n')
                             new_file.write('""""""""""""""""""""\n')
                             new_file.write('.. inheritance-diagram:: ' + name)
-                            new_file.write('    :parts: 1')
+                            new_file.write('    :parts: 1\n')
                             new_file.write('')
                             new_file.write('')