Merge pull request #9 from kmlefran/docs

Update API documentation

docs/source/conf.py

@@ -260,7 +260,10 @@
     ),
     ("py:class", "SinglefileData"),
     ("py:class", "Int"),
+    ("py:class", "Str"),
     ("py:class", "Code"),
     ("py:class", "QbFields"),
+    ("py:class", "StructureData"),
+    ("py:class", "Bool"),
     ("py:obj", "aiida_submission_controller.FromGroupSubmissionController"),
 ]

docs/source/reference/api/auto/aiida_aimall/calculations/index.rst

@@ -22,18 +22,6 @@ Classes
 
 
 
-Attributes
-~~~~~~~~~~
-
-.. autoapisummary::
-
-   aiida_aimall.calculations.AimqbParameters
-
-
-.. py:data:: AimqbParameters
-
-
-
 .. py:class:: AimqbCalculation(*args, **kwargs)
 
 
@@ -51,25 +39,25 @@ Attributes
 
       the wfx, wfn, or fchk file to be run
 
-      :type: SinglefileData
+      :type: `SinglefileData`
 
    .. attribute:: code
 
       code of the AIMQB executable
 
-      :type: Code
+      :type: `Code`
 
    .. attribute:: attached_atom_int
 
-      the integer label of the atom in the group that is attached to the rest of the molecule
+      otional integer label of the atom in the group that is attached to the rest of the molecule
 
-      :type: Int
+      :type: `Int`
 
    .. attribute:: group_atoms
 
-      integer ids of atoms comprising the group for AimqbGroupParser
+      optional integer ids of atoms comprising the group for AimqbGroupParser
 
-      :type: List(Int)
+      :type: `List(int)`
 
    .. rubric:: Example
 
@@ -92,12 +80,17 @@ Attributes
    .. note::
 
       By default, the AimqbBaseParser is used, getting atomic, BCP, and (if applicable) LapRhoCps.
-          You can opt to use the AimqbGroupParser, which also returns the integrated group properties model
-          of a group, as well as the atomic graph descriptor of the group. This is done by providing this to the builder:
+          You can opt to use the AimqbGroupParser, which also returns the integrated group properties
+          of a group, as well as the atomic graph descriptor of the group. In doing so, you can also
+          define the atoms included in the group, which, by convention, defaults to all atoms except atom 2.
+          You can further specify which atom of the group is the one bonded to the substrate, which defaults to
+          atom 1.  This is done by providing this to the builder:
 
       ::
 
           builder.metadata.options.parser_name = "aimall.group"
+          builder.attached_atom_int = Int(1)
+          builder.group_atoms = List([1,3,4,5,6])
 
    .. py:attribute:: INPUT_FILE
       :value: 'aiida.wfx'

docs/source/reference/api/auto/aiida_aimall/controllers/index.rst

@@ -31,44 +31,31 @@ Classes
 
 
 
-Attributes
-~~~~~~~~~~
-
-.. autoapisummary::
-
-   aiida_aimall.controllers.AimqbParameters
-   aiida_aimall.controllers.GaussianCalculation
-   aiida_aimall.controllers.AimqbCalculation
-
-
-.. py:data:: AimqbParameters
-
-
-
-.. py:data:: GaussianCalculation
-
-
-
-.. py:data:: AimqbCalculation
-
-
-
 .. py:class:: SmilesToGaussianController(code_label: str, gauss_opt_params: dict, wfxgroup: str, nprocs: int, mem_mb: int, time_s: int, *args, **kwargs)
 
 
    Bases: :py:obj:`aiida_submission_controller.FromGroupSubmissionController`
 
    A controller for submitting :func:`aiida_aimall.workchains.param_parts.SmilesToGaussianWorkChain`
 
-   :param parent_group_label: the string of a group label which contains various SMILES as orm.Str nodes
-   :param group_label: the string of the group to put the GaussianCalculations in
-   :param max_concurrent: maximum number of concurrent processes.
-   :param code_label: label of code, e.g. gaussian@cedar
-   :param gauss_opt_params: Dict of Gaussian parameters to use
+   :param parent_group_label: group label which contains various SMILES as orm.Str nodes
+   :type parent_group_label: `str`
+   :param group_label: group in which to put the GaussianCalculations
+   :type group_label: `str`
    :param wfxgroup: group in which to store the resulting wfx files
+   :type wfxgroup: `str`
+   :param max_concurrent: maximum number of concurrent processes
+   :type max_concurrent: `int`
+   :param code_label: label of Gaussian code, e.g. gaussian@cedar
+   :type code_label: `str`
+   :param gauss_opt_params: Dict of Gaussian parameters to use
+   :type gauss_opt_params: `Dict`
    :param nprocs: number of processors for gaussian calculation
+   :type nprocs: `int`
    :param mem_mb: amount of memory in MB for Gaussian calculation
+   :type mem_mb: `int`
    :param time_s: wallclock time in seconds for Gaussian calculation
+   :type time_s: `int`
 
    :returns: Controller object, periodically use run_in_batches to submit new results
 

docs/source/reference/api/auto/aiida_aimall/data/index.rst

@@ -46,6 +46,13 @@ Attributes
    The class takes a dictionary of parameters and validates
    to ensure the aimqb command line parameters are correct
 
+   :param parameters_dict: dictionary with commandline parameters
+   :type parameters_dict: `dict`
+
+   Usage:
+       ``AimqbParameters(parameter_dict{'naat':2})``
+
+
    .. py:attribute:: schema
 
 
@@ -59,26 +66,26 @@ Attributes
           print(AimqbParameters).schema.schema
 
       :param parameters_dict: dictionary with commandline parameters
-      :param type parameters_dict: dict
-      :returns: validated dictionary
+      :type parameters_dict: dict
 
+      :returns: input dictionary validated against the allowed options for aimqb
 
-   .. py:method:: cmdline_params(file_name)
 
-      Synthesize command line parameters.
+   .. py:method:: cmdline_params(file_name)
 
-      e.g. [ '-atlaprhocps=True',...,'-nogui', 'filename']
+      Synthesize command line parameters and add -nogui for use in `AimqbCalculation`.
 
       :param file_name: Name of wfx/fchk/wfn file
-      :param type file_name: str
+      :type file_name: str
 
+      :returns:
 
+                command line parameters for aimqb collected in a list
+                    e.g. [ '-atlaprhocps=True',...,'-nogui', 'filename']
 
-   .. py:method:: __str__()
 
-      String representation of node.
+   .. py:method:: __str__()
 
-      Append values of dictionary to usual representation. E.g.::
+      String representation of node. Append values of dictionary to usual representation.
 
-          uuid: b416cbee-24e8-47a8-8c11-6d668770158b (pk: 590)
-          {'atlaprhocps': True}
+      :returns: representation of node, including uuid, pk, and the contents of the dictionary

docs/source/reference/api/auto/aiida_aimall/index.rst

@@ -3,13 +3,6 @@
 
 .. py:module:: aiida_aimall
 
-.. autoapi-nested-parse::
-
-   aiida_aimall
-
-   A plugin to interface AIMAll with AiiDA
-
-
 
 Subpackages
 -----------

docs/source/reference/api/auto/aiida_aimall/workchains/calcfunctions/index.rst

@@ -31,6 +31,7 @@ Functions
    aiida_aimall.workchains.calcfunctions.get_wfxname_from_gaussianinputs
    aiida_aimall.workchains.calcfunctions.create_wfx_from_retrieved
    aiida_aimall.workchains.calcfunctions.validate_shell_code
+   aiida_aimall.workchains.calcfunctions.validate_parser
    aiida_aimall.workchains.calcfunctions.validate_file_ext
    aiida_aimall.workchains.calcfunctions.get_molecule_str_from_smiles
    aiida_aimall.workchains.calcfunctions.xyzfile_to_StructureData
@@ -42,6 +43,7 @@ Functions
    Rotates the fragment to the defined coordinate system
 
    :param FolderData: aim calculation folder
+   :type FolderData: aiida.orm.FolderData
    :param atom_dict: AIM atom dict
    :param cc_dict: AIM cc_dict
 
@@ -65,13 +67,14 @@ Functions
           to just symbols
 
 
-.. py:function:: dict_to_structure(fragment_dict: aiida.orm.Dict)
+.. py:function:: dict_to_structure(fragment_dict)
 
    Generate a StructureData for Gaussian inputs
 
    :param fragment_dict: AiiDA orm.Dict with keys 'atom_symbols' and 'geom'
+   :type fragment_dict: aiida.orm.Dict
 
-   :returns: StructureData for the molecule
+   :returns: aiida.orm.StructureData for the molecule
 
    .. note::
 
@@ -183,6 +186,15 @@ Functions
    :returns: None if the type is ShellCode or Str, or error string if node is not
 
 
+.. py:function:: validate_parser(node, _)
+
+   Validate the parser, ensuring that the provided value is one of the accepted values.
+
+   :param node: input node to check the type for ShellCode or Str
+
+   :returns: None if the value is aimall.base or aimall.group, or an error string if it is not
+
+
 .. py:function:: validate_file_ext(node, _)
 
    Validates that the file extension provided for AIM is wfx, wfn or fchk

docs/source/reference/api/auto/aiida_aimall/workchains/input/index.rst

@@ -27,8 +27,34 @@ Classes
 
    Bases: :py:obj:`aiida.engine.WorkChain`
 
-   A workchain to generate and validate inputs. One of SinglefileData, Smiles as Str or StructureData should be
-   provided
+   A workchain to generate and validate inputs.
+
+   Provided an .xyz file as `SinglefileData`, molecule `StructureData`, or SMILES of the molecule
+   validates that only one is provided. Then, prepares the input into a format for future GaussianCalculations.
+
+   .. attribute:: structure
+
+      StructureData of molecule to run
+
+      :type: aiida.orm.StructureData
+
+   .. attribute:: smiles
+
+      smiles string of molecule
+
+      :type: aiida.orm.Str
+
+   .. attribute:: xyz_file
+
+      file data of an xyz file
+
+      :type: aiida.orm.SinglefileData
+
+   .. note::
+
+      This is a base class that is used by other WorkChains
+          (:func:`aiida_aimall.workchains.subparam.SubstituentParameterWorkChain`, and
+          :func:`aiida_aimall.workchains.qc_programs.GaussianToAIMWorkChain`)
 
    .. py:method:: define(spec)
       :classmethod: