sphinx.ext.pngmath is now sphinx.ext.imgmath (#471)

* sphinx.ext.pngmath is now sphinx.ext.imgmath * configure bibtex_bibfiles setting * quick pass on the docs, plenty more to fix but will take care of it later * add warning to the docs * add warning to readme
choderalab · Jul 28, 2022 · a314f00 · a314f00
1 parent 50dfbc9
commit a314f00
Show file tree

Hide file tree

Showing 9 changed files with 41 additions and 33 deletions.
diff --git a/README.md b/README.md
@@ -4,9 +4,13 @@
 [![PyPI Version](https://badge.fury.io/py/pymbar.png)](https://pypi.python.org/pypi/pymbar)
 [![DOI](https://zenodo.org/badge/9991771.svg)](https://zenodo.org/badge/latestdoi/9991771)
 
-pymbar
+pymbar 3 LTS
 ======
 
+**Warning**
+You are looking at the documentation for pymbar 3 LTS.
+If you want the latest version, look [here](https://github.com/choderalab/pymbar)
+
 Python implementation of the [multistate Bennett acceptance ratio (MBAR)](http://www.alchemistry.org/wiki/Multistate_Bennett_Acceptance_Ratio) method for estimating expectations and free energy differences from equilibrium samples from multiple probability densities.
 See our [docs](http://pymbar.readthedocs.org/en/latest/).
 
@@ -16,15 +20,11 @@ Installation
 
 The easiest way to install the `pymbar` release is via [conda](http://conda.pydata.org):
 ```bash
-conda install -c conda-forge pymbar
-```
-You can also install `pymbar` from the [Python package index](https://pypi.python.org/pypi/pymbar) using `pip`:
-```bash
-pip install pymbar
+conda install -c conda-forge "pymbar<4"
 ```
 The development version can be installed directly from github via `pip`:
 ```bash
-pip install git+https://github.com/choderalab/pymbar.git
+pip install git+https://github.com/choderalab/pymbar.git@pymbar-3-lts
 ```
 
 Usage

diff --git a/docs/conf.py b/docs/conf.py
@@ -44,15 +44,15 @@
 #    'sphinx.ext.autosummary'
 #]
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx',
-              'sphinx.ext.todo', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig',
+              'sphinx.ext.todo', 'sphinx.ext.imgmath', 'sphinx.ext.ifconfig',
               'numpydoc', 'sphinx.ext.inheritance_diagram',
               'sphinx.ext.autosummary', 'sphinx.ext.extlinks',
               'sphinxcontrib.bibtex']
 
 autosummary_generate = True
 autodoc_default_flags = ['members', 'inherited-members']
 numpydoc_show_class_members = False
-
+bibtex_bibfiles = ["references.bib"]
 # concatenate both class and __init__ docstrings when generating autodoc class
 # docs
 autoclass_content = 'both'
@@ -92,7 +92,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -168,7 +168,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -313,3 +313,7 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+rst_prolog = """.. attention::
+    You are looking at the documentation for the pymbar 3 LTS branch.
+    If you want to update to the latest pymbar version, see this page https://pymbar.readthedocs.io/en/stable/moving_from_pymbar3.html
+"""
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -11,26 +11,27 @@ Installing ``pymbar``
 conda (recommended)
 -------------------
 
-The easiest way to install the ``pymbar`` release is via `conda <http://conda.pydata.org>`_:
+This documentation covers ``pymbar`` 3.
+This is a long term support branch of ``pymbar``.
+The easiest way to install the LTS version of ``pymbar`` release is via `conda <http://conda.pydata.org>`_:
 
-::
-   $ conda install -c conda-forge pymbar
+.. code-block:: console
 
-pip
----
+   $ conda install -c conda-forge "pymbar<4"
 
-You can also install ``pymbar`` from the `Python package index <https://pypi.python.org/pypi/pymbar>`_ using ``pip``:
+pip (pypi)
+----------
 
-::
-   $ pip install pymbar
+Note: We are currently not releasing new versions of the LTS branch on ``PyPI``.
 
 Development version
 -------------------
 
 The development version can be installed directly from github via ``pip``:
 
-::
-   $ pip install git+https://github.com/choderalab/pymbar.git
+.. code-block:: console
+
+   $ pip install git+https://github.com/choderalab/pymbar.git@pymbar-3-lts
 
 Running the tests
 =================
@@ -42,5 +43,6 @@ The test suite uses `pytest <https://pytest.readthedocs.org/en/latest/>`_, in ad
 
 You can then run the tests with:
 
-::
+.. code-block:: console
+
    $ pytest -vv pymbar
diff --git a/docs/index.rst b/docs/index.rst
@@ -18,8 +18,8 @@ Documentation
    getting_started
    mbar
    timeseries
-   testsystems
-   references
+   utils
+   zbibliography
 
 Indices and tables
 ==================

diff --git a/docs/mbar.rst b/docs/mbar.rst
@@ -5,4 +5,5 @@ The :mod:`mbar` module: :class:`MBAR`
 
 The :mod:`mbar` module contains the :class:`MBAR` class, which implements the `multistate Bennett acceptance ratio (MBAR) <http://www.alchemistry.org/wiki/Multistate_Bennett_Acceptance_Ratio>`_ method :cite:`shirts-chodera:jcp:2008:mbar`.
 
-.. automodule:: pymbar.mbar
+.. autoclass:: pymbar.MBAR
+   :members:
diff --git a/docs/testsystems.rst b/docs/testsystems.rst
@@ -12,4 +12,3 @@ These test systems are also convenient to use if you want to easily generate syn
 .. automodule:: pymbar.testsystems.timeseries
 .. automodule:: pymbar.testsystems.exponential_distributions
 .. automodule:: pymbar.testsystems.gaussian_work
-.. automodule:: pymbar.testsystems.pymbar_datasets
diff --git a/docs/timeseries.rst b/docs/timeseries.rst
@@ -67,3 +67,4 @@ A number of other useful functions for computing autocorrelation functions from
 same process are also provided.
 
 .. automodule:: pymbar.timeseries
+   :members:
diff --git a/docs/utils.rst b/docs/utils.rst
@@ -6,3 +6,4 @@ Utilities : :mod:`pymbar.utils`
 These functions are some miscellaneous functions used by other parts of the ``pymbar`` library.
 
 .. automodule:: pymbar.utils
+   :members:
diff --git a/pymbar/mbar.py b/pymbar/mbar.py
@@ -330,12 +330,12 @@ def __init__(self, u_kn, N_k, maximum_iterations=10000, relative_tolerance=1.0e-
                     # pick new random ones of these K.
                     new_kindices = k_indices[np.random.randint(int(N_k[k]), size=int(N_k[k]))]
                     rinit[k_indices] = new_kindices
-                
+
                 self.f_k_boots[b,:] = mbar_solvers.solve_mbar_for_all_states(self.u_kn[:,rinit], self.N_k, f_k_init, solver_protocol, solver_tolerance)
                 if verbose:
                     if b%10==0:
-                        print("Calculated {:d}/{:d} bootstrap samples".format(b,self.nbootstraps)) 
-                        
+                        print("Calculated {:d}/{:d} bootstrap samples".format(b,self.nbootstraps))
+
         self.Log_W_nk = mbar_solvers.mbar_log_W_nk(self.u_kn, self.N_k, self.f_k)
 
         # Print final dimensionless free energies.
@@ -688,7 +688,7 @@ def computeExpectationsInner(self, A_n, u_ln, state_map,
         >>> results = mbar.computeExpectationsInner(A_n, u_n, state_map)
 
         """
-        
+
         logfactor = 4.0 * np.finfo(np.float64).eps
         # make sure all results are larger than this number.
         # We tried 1 before, but expecations that are all very small (like
@@ -1115,9 +1115,9 @@ def computeMultipleExpectations(self, A_in, u_n, compute_uncertainty=True, compu
         which is the energy of the n samples evaluated at a the chosen
         state.
 
-        
+
         Parameters:
-        -------------
+        -----------
 
         A_in : np.ndarray, float, shape=(I, k, N)
             A_in[i,n] = A_i(x_n), the value of phase observable i for configuration n at state of interest
@@ -1136,7 +1136,7 @@ def computeMultipleExpectations(self, A_in, u_n, compute_uncertainty=True, compu
             If true, return is a dictionary, else its a tuple
 
         Returns
-        -------------
+        -------
         'mu' : np.ndarray, float, shape=(I)
             result_vals['mu'] is the estimate for the expectation of A_i(x) at the state specified by u_kn
             If return_dict, key will be 'mu'