Add docs for the CLI

adosar · adosar · commit 24422302ba5f · 2024-05-25T18:50:25.000+03:00
* utils.get_names is replaed with utils.load_json
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -19,3 +19,4 @@ sphinxcontrib-qthelp
 sphinxcontrib-serializinghtml
 sphinxemoji
 sphinx-issues
+sphinxcontrib-programoutput
diff --git a/docs/source/changes.rst b/docs/source/changes.rst
@@ -1,5 +1,17 @@
-|:pushpin:| Changes
-===================
+|:pushpin:| Changelog
+=====================
+
+Version 0.1.2
+-------------
+
+.. versionadded:: 0.1.2
+
+   * :func:`moxel.utils.load_json`
+   * Documentation for the :ref:`cli`.
+
+.. versionremoved:: 0.1.2
+
+   * :func:`moxel.utils.get_names`
 
 Version 0.1.1
 -------------
@@ -21,13 +33,14 @@ Version 0.1.0
     * The usage of the CLI is now ``moxel <command>`` instead of ``python -m
       moxel``.
 
-.. versionremoved:: 0.1.0
-
-    * Easy imports, such as ``from moxel import Grid``.
-    * :func:`moxel.utils.batch_clean_and_merge`
-
 .. versionadded:: 0.1.0
 
     * :func:`moxel.utils.batch_clean`
     * :func:`moxel.visualize.plot_voxels_pv` for faster visualization.
     * Optional parameter ``n_jobs`` for specifying number of cores.
+
+.. versionremoved:: 0.1.0
+
+    * Easy imports, such as ``from moxel import Grid``.
+    * :func:`moxel.utils.batch_clean_and_merge`
+
diff --git a/docs/source/cli.rst b/docs/source/cli.rst
@@ -5,6 +5,16 @@
 
 There are two available commands: ``[create, clean]``
 
-.. code-block:: console
+``moxel``
+---------
+.. program-output:: moxel --help
 
-       $ moxel <command> --help
+``moxel create``
+----------------
+
+.. program-output:: moxel create --help
+
+``moxel clean``
+---------------
+
+.. program-output:: moxel clean --help
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -28,6 +28,7 @@
         'sphinxarg.ext',
         'sphinx_code_tabs',
         'sphinx_issues',
+        'sphinxcontrib.programoutput',
         ]
 
 templates_path = ['_templates']
diff --git a/docs/source/moxel.rst b/docs/source/moxel.rst
@@ -3,29 +3,14 @@
 |:books:| API Documentation
 ---------------------------
 
-moxel package
-=============
-
 .. automodule:: moxel
    :members:
    :undoc-members:
    :show-inheritance:
 
-Submodules
-==========
-
-moxel.utils
-===========
-
-.. automodule:: moxel.utils
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-moxel.visualize
-===============
+.. toctree::
+   :maxdepth: 2
+   :caption: Submodules:
 
-.. automodule:: moxel.visualize
-   :members:
-   :undoc-members:
-   :show-inheritance:
+   utils
+   visualize
diff --git a/docs/source/utils.rst b/docs/source/utils.rst
@@ -0,0 +1,7 @@
+moxel.utils
+===========
+
+.. automodule:: moxel.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/visualize.rst b/docs/source/visualize.rst
@@ -0,0 +1,7 @@
+moxel.visualize
+===============
+
+.. automodule:: moxel.visualize
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/pyproject.toml b/pyproject.toml
@@ -39,7 +39,7 @@ dependencies = [
 [project.urls]
 Homepage = "https://github.com/adosar/moxel"
 Documentation = "https://moxel.readthedocs.io"
-Changelog = "https://moxel.readthedocs.io/en/stable/changes.html"
+Changelog = "https://moxel.readthedocs.io/en/stable/changelog.html"
 
 [project.scripts]
-moxel = "moxel.cli:moxel_fire"
+moxel = "moxel._cli:moxel_fire"
diff --git a/src/moxel/_cli.py b/src/moxel/_cli.py
@@ -14,12 +14,19 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 
+r"""
+This module provides helper functions for the CLI.
+"""
+
 import fire
 from . utils import voxels_from_dir, batch_clean
 
 
 def moxel_fire():
-  fire.Fire({
-      'clean': batch_clean,
-      'create': voxels_from_dir,
-  })
+    r"""
+    Run the CLI.
+    """
+    fire.Fire({
+        'clean': batch_clean,
+        'create': voxels_from_dir,
+    })
diff --git a/src/moxel/_params.py b/src/moxel/_params.py
@@ -14,6 +14,10 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 
+r"""
+This module provides the Lennard-Jones parameters from UFF.
+"""
+
 lj_params = {
     "H": [
         22.11417,
diff --git a/src/moxel/utils.py b/src/moxel/utils.py
@@ -49,9 +49,9 @@
 warnings.filterwarnings('ignore')
 
 
-def get_names(fname):
+def load_json(fname):
     r"""
-    Load a list of material names saved in ``.json`` format.
+    Load a ``.json`` file.
 
     Parameters
     ----------
@@ -63,9 +63,9 @@ def get_names(fname):
     names : list
     """
     with open(fname, 'r') as fhand:
-        names = json.load(fhand)
+        data = json.load(fhand)
 
-    return names
+    return data
 
 
 def mic_scale_factors(r, lattice_vectors):
@@ -168,8 +168,8 @@ def calculate(self, cubic_box=False, length=30, potential='lj', n_jobs=None):
             The size of the cubic box in Å. Takes effect only
             if ``cubic_box == True``.
         n_jobs : int, optional
-            Number of jobs to run in parallel. If ``None``, all processors are
-            used.
+            Number of jobs to run in parallel. If ``None``, then the number returned
+            by ``os.cpu_count()`` is used.
 
         Returns
         -------
@@ -278,7 +278,8 @@ def voxels_from_file(
     length : float, default=30
         The size of the cubic box in Å. Takes effect only if ``cubic_box == True``.
     n_jobs : int, optional
-        Number of jobs to run in parallel. If ``None``, all processors are used.
+        Number of jobs to run in parallel. If ``None``, then the number returned
+        by ``os.cpu_count()`` is used.
     only_voxels : bool, default=True
         Determines ``out`` type.
         
@@ -301,8 +302,8 @@ def voxels_from_file(
 
     if only_voxels:
         return grid.voxels
-    else:
-        return grid
+
+    return grid
 
 
 def voxels_from_files(
@@ -467,7 +468,7 @@ def batch_clean(batch_dirname):
         If no voxels are missing ``0`` else ``1``.
     """
     # Case 1: no missing voxels.
-    names = get_names(f'{batch_dirname}/names.json')
+    names = load_json(f'{batch_dirname}/names.json')
     voxels = np.load(f'{batch_dirname}/voxels.npy', mmap_mode='r')
 
     missing_idx = [i for i, x in enumerate(voxels) if np.all(x == 0)]
diff --git a/src/moxel/visualize.py b/src/moxel/visualize.py
@@ -64,7 +64,7 @@ def plot_voxels_mpl(voxels, *, fill_pattern=None, colorbar=True, cmap='viridis',
     >>> plt.show()  # Not needed for Jupyter.
     """
 
-    if np.all(fill_pattern) == None:
+    if np.all(fill_pattern) is None:
         fill_pattern = np.full(voxels.shape, True)
 
     cmap = plt.get_cmap(cmap)
diff --git a/tests/test_utils.py b/tests/test_utils.py
@@ -106,7 +106,7 @@ def test_voxels_from_files(self):
             voxels_from_files(cif_files, out_pathname=dir_path, grid_size=grid_size)
 
             voxels = np.load(f'{dir_path}/voxels.npy', mmap_mode='r')
-            stored_names = get_names(f'{dir_path}/names.json')
+            stored_names = load_json(f'{dir_path}/names.json')
 
             self.assertEqual(voxels.shape, (n_files, grid_size, grid_size, grid_size))
             self.assertEqual(names, stored_names)
@@ -126,7 +126,7 @@ def test_voxels_from_dir(self):
             voxels_from_dir(cif_dir, dir_path, grid_size=grid_size)
 
             voxels = np.load(f'{dir_path}/voxels.npy', mmap_mode='r')
-            stored_names = get_names(f'{dir_path}/names.json')
+            stored_names = load_json(f'{dir_path}/names.json')
 
             self.assertEqual(voxels.shape, (n_files, grid_size, grid_size, grid_size))
             self.assertEqual(names, stored_names)
@@ -145,10 +145,10 @@ def test_batch_clean(self):
             batch_clean(dir_path)
 
             voxels = np.load(f'{dir_path}/voxels.npy', mmap_mode='r')
-            names = get_names(f'{dir_path}/names.json')
+            names = load_json(f'{dir_path}/names.json')
 
             clean_voxels = np.load(f'{dir_path}/clean_voxels.npy', mmap_mode='r')
-            clean_names = get_names(f'{dir_path}/clean_names.json')
+            clean_names = load_json(f'{dir_path}/clean_names.json')
 
             # Get the indices of filled voxels.
             filled_idx = [i for i, x in enumerate(voxels) if not np.all(x == 0)]

Original file line number	Diff line number	Diff line change
`@@ -28,6 +28,7 @@`
`28`	`28`	`'sphinxarg.ext',`
`29`	`29`	`'sphinx_code_tabs',`
`30`	`30`	`'sphinx_issues',`
	`31`	`+ 'sphinxcontrib.programoutput',`
`31`	`32`	`]`
`32`	`33`
`33`	`34`	`templates_path = ['_templates']`