From 0a954cfd7201c2bc4abb4bce5119dd2d25cbf2a2 Mon Sep 17 00:00:00 2001
From: Antonios Sarikas <antonios.sarikas@gmail.com>
Date: Tue, 7 May 2024 14:10:05 +0300
Subject: [PATCH] Fix docs

---
 README.md                |  9 +++++----
 docs/requirements.txt    |  1 +
 docs/source/changes.rst  |  6 ++++++
 docs/source/conf.py      | 14 ++++++++++++++
 docs/source/index.rst    |  4 ++--
 docs/source/tutorial.rst | 14 ++++++++++++++
 src/moxel/utils.py       | 14 ++++++++++++++
 7 files changed, 56 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 5008afd..ae5cf60 100644
--- a/README.md
+++ b/README.md
@@ -54,13 +54,14 @@ If you use ΜΟΧελ in your research, please consider citing the following wor
     publisher = {Springer Science and Business Media LLC},
     author = {Sarikas,  Antonios P. and Gkagkas,  Konstantinos and Froudakis,  George E.},
     year = {2024},
-    month = jan 
+    month = jan
     }
 
 ## 📇 TODO
-* Improve modeling of interactions
-* Improve voxelization scheme
-* Improve performance
+1. CLI for training [RetNet](https://www.nature.com/articles/s41598-023-50309-8).
+2. Improve performance
+3. Improve voxelization scheme
+4. Improve modeling of interactions
 
 ## 📑 License
 MOXελ is released under the [GNU General Public License v3.0 only](https://spdx.org/licenses/GPL-3.0-only.html).
diff --git a/docs/requirements.txt b/docs/requirements.txt
index f243f3c..edf2cd5 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -18,3 +18,4 @@ sphinxcontrib-jsmath
 sphinxcontrib-qthelp
 sphinxcontrib-serializinghtml
 sphinxemoji
+sphinx-issues
diff --git a/docs/source/changes.rst b/docs/source/changes.rst
index a8a9e3a..efff5a4 100644
--- a/docs/source/changes.rst
+++ b/docs/source/changes.rst
@@ -1,6 +1,12 @@
 |:pushpin:| Changes
 ===================
 
+Version 0.1.1
+-------------
+    
+* Add performance enhancements proposed by :user:`fxcoudert`. See PR :pr:`2, 3`.
+* Fix bug in :mod:`moxel.visualize` where plots didn't render.
+
 Version 0.1.0
 -------------
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 87c717e..ff28918 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -27,6 +27,7 @@
         'sphinx_copybutton',
         'sphinxarg.ext',
         'sphinx_code_tabs',
+        'sphinx_issues',
         ]
 
 templates_path = ['_templates']
@@ -40,3 +41,16 @@
 
 html_theme = 'sphinx_rtd_theme'
 #html_static_path = ['_static']
+
+# Path to GitHub repo {group}/{project}  (note that `group` is the GitHub user or organization)
+issues_github_path = "adosar/moxel"
+
+# which is the equivalent to:
+issues_uri = "https://github.com/{group}/{project}/issues/{issue}"
+issues_prefix = "#"
+issues_pr_uri = "https://github.com/{group}/{project}/pull/{pr}"
+issues_pr_prefix = "#"
+issues_commit_uri = "https://github.com/{group}/{project}/commit/{commit}"
+issues_commit_prefix = "@"
+issues_user_uri = "https://github.com/{user}"
+issues_user_prefix = "@"
diff --git a/docs/source/index.rst b/docs/source/index.rst
index b698640..ce83d0a 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -75,8 +75,8 @@ If you use ΜΟΧελ in your research, please consider citing the following wor
 TODO
 ----
 
-1. Improve performance
-2. CLI for training `RetNet <https://www.nature.com/articles/s41598-023-50309-8>`_
+1. CLI for training `RetNet <https://www.nature.com/articles/s41598-023-50309-8>`_
+2. Improve performance
 3. Improve voxelization scheme
 4. Improve modeling of interactions
 
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
index eade600..96cb5e6 100644
--- a/docs/source/tutorial.rst
+++ b/docs/source/tutorial.rst
@@ -47,6 +47,20 @@ In all cases, :func:`moxel.utils.Grid.calculate` is used under the hood to calcu
 voxels (all other functions are just wrappers). To better understand how to use
 them: :ref:`documentation`.
 
+.. attention::
+    Consider playing with the ``n_jobs`` parameter to get the best performance
+    for your system::
+
+        from timeit import timeit
+
+        setup = 'from moxel.utils import voxels_from_file'
+        n_jobs = [1, 2, 8, 16]  # Modify this according to your system.
+
+        for n in n_jobs:
+            stmt = f'voxels_from_file("path/to/cif", n_jobs={n})'
+            time = timeit(stmt=stmt, setup=setup, number=1)
+            print(f'Time with {n} jobs: {time:.3f} s')
+
 Visualization
 ^^^^^^^^^^^^^
 
diff --git a/src/moxel/utils.py b/src/moxel/utils.py
index 23c9720..dbfcfd7 100644
--- a/src/moxel/utils.py
+++ b/src/moxel/utils.py
@@ -19,6 +19,20 @@
 
 .. note::
     Currently, interactions are modelled with the Lennard-Jones (LJ) potential.
+
+.. attention::
+    Consider playing with the ``n_jobs`` parameter to get the best performance
+    for your system::
+
+        from timeit import timeit
+
+        setup = 'from moxel.utils import voxels_from_file'
+        n_jobs = [1, 2, 8, 16]  # Modify this according to your system.
+
+        for n in n_jobs:
+            stmt = f'voxels_from_file("path/to/cif", n_jobs={n})'
+            time = timeit(stmt=stmt, setup=setup, number=1)
+            print(f'Time with {n} jobs: {time:.3f} s')
 """
 
 import os