Docs by nhew1994 · Pull Request #19 · PhasesResearchLab/pyzentropy

nhew1994 · 2026-02-06T21:48:46Z

No description provided.

Update docs from main

Updated the math formatting for the partition function in the docstring.

Removed detailed explanation of partition function calculation and simplified the description.

Copilot

Pull request overview

This PR updates the project’s documentation and docstrings to provide richer API reference material and a reorganized Sphinx docs site structure.

Changes:

Expanded and standardized docstrings for core classes/functions (System, Configuration, Plotly formatting helpers).
Reworked Sphinx docs structure (new _source pages, new API landing page, new autoclass/autmodule pages; removed legacy docs/api/* structure).
Updated Sphinx configuration and added standard build entrypoints (Makefile/make.bat), plus refreshed README installation instructions.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
pyzentropy/system.py	Expanded class/method docstrings and minor refactors to improve readability.
pyzentropy/configuration.py	Expanded class/method docstrings and clarified plotting API docs.
pyzentropy/plotly_utils.py	Added return type annotation and updated docstring formatting.
docs/conf.py	Reworked Sphinx configuration and linkcode behavior.
docs/index.rst	New docs landing structure including overview + reorganized toctrees.
docs/api.rst	New consolidated API Reference toctree.
docs/pyzentropy.system.rst	New autoclass page for `System`.
docs/pyzentropy.configuration.rst	New autoclass page for `Configuration`.
docs/pyzentropy.utilities.rst	New/updated utilities API page for `plotly_utils`.
docs/_source/overview.rst	New overview content describing zentropy method and capabilities.
docs/_source/installation.md	New Markdown-based installation guide under `_source`.
docs/_source/tutorials.md	New Tutorials landing page under `_source`.
docs/Makefile	Added standard Sphinx make targets for Unix-like environments.
docs/make.bat	Added standard Sphinx build script for Windows environments.
docs/requirements.txt	Minor formatting adjustment for docs dependency list.
docs/installation.rst	Removed old installation page (replaced by `_source/installation.md`).
docs/api/pyzentropy.system.rst	Removed legacy automodule API page (superseded by new structure).
docs/api/pyzentropy.configuration.rst	Removed legacy automodule API page (superseded by new structure).
docs/api/api_utilities.rst	Removed legacy API toctree.
docs/api/api_system.rst	Removed legacy API toctree.
docs/api/api_configuration.rst	Removed legacy API toctree.
docs/api/api.rst	Removed legacy API index page.
README.md	Updated installation instructions and headings to match new docs.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-06T21:53:58Z

pyzentropy/system.py

+        The configuration partition functions :math:`Z_k(T, V)` are first
+        computed. Then, the total partition function of the system is
+        then obtained by summing over all configurations:
+        :math:`Z(T, V) = \sum_k g_k Z_k`.


This :math: role contains \sum in a normal (non-raw) docstring, which triggers an “invalid escape sequence” warning at import/compile time. Use a raw docstring or escape the backslash (e.g., \\sum) so the LaTeX is preserved without Python warnings.

Copilot · 2026-02-06T21:53:59Z

pyzentropy/configuration.py

            Helmholtz free energies :math:`F_k(T, V)`.
-        helmholtz_energies_dV (np.ndarray):
+        helmholtz_energies_dV:
            First volume derivatives :math:`\partial F_k / \partial V`.
-        helmholtz_energies_d2V2 (np.ndarray):
+        helmholtz_energies_d2V2:
            Second volume derivatives :math:`\partial^2 F_k / \partial V^2`.


This docstring section includes LaTeX commands with backslashes (e.g., \partial) inside a normal Python string literal, which produces “invalid escape sequence” warnings at import/compile time. Use a raw docstring (r"""...""") or escape backslashes (\\partial, etc.) so the math renders without warnings.

Copilot · 2026-02-06T21:53:59Z

pyzentropy/configuration.py

+        helmholtz_energies:
            Helmholtz free energies :math:`F_k(T, V)`.
-        helmholtz_energies_dV (np.ndarray):
+        helmholtz_energies_dV:
            First volume derivatives :math:`\partial F_k / \partial V`.
-        helmholtz_energies_d2V2 (np.ndarray):
+        helmholtz_energies_d2V2:
            Second volume derivatives :math:`\partial^2 F_k / \partial V^2`.


Same issue as above: the Attributes portion of the docstring contains \partial / \partial^2 in a non-raw docstring, which triggers “invalid escape sequence” warnings. Use raw docstrings or escape the backslashes in these math expressions.

Copilot · 2026-02-06T21:53:59Z

docs/index.rst

 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   _source/installation
+   _source/tutorials
+   api
   :hidden:
+   :maxdepth: 2
+   :caption: USER GUIDE


In reST, .. toctree:: option lines (e.g., :hidden:, :maxdepth:, :caption:) must appear immediately after the directive and before any entries. As written, the options come after the listed documents, which Sphinx will treat as additional entries and/or emit warnings. Move the option lines above _source/installation, _source/tutorials, and api (and similarly for the later toctrees).

Copilot · 2026-02-06T21:53:59Z

docs/api.rst

+   pyzentropy.configuration
+   pyzentropy.system
+   pyzentropy.utilities
+   :maxdepth: 6


.. toctree:: options must be placed before the file list. With :maxdepth: after the entries, Sphinx will not apply the option as intended (and may warn about an unknown document named :maxdepth: 6). Reorder so :maxdepth: comes right after the directive, then list the pyzentropy.* pages.

Suggested change

pyzentropy.configuration

pyzentropy.system

pyzentropy.utilities

:maxdepth: 6

:maxdepth: 6

pyzentropy.configuration

pyzentropy.system

pyzentropy.utilities

Copilot · 2026-02-06T21:54:00Z

docs/conf.py

+project = 'pyzentropy'
+copyright = '2026, Nigel Lee En Hew'
+author = 'Nigel Lee En Hew'
+release = '0.1.0'
+__version__ = release

-# -- Options for napoleon ----------------------------------------------------
-napoleon_google_docstring = True
-napoleon_numpy_docstring = True
-napoleon_include_init_with_doc = False
-napoleon_include_private_with_doc = False
-napoleon_include_special_with_doc = True
-napoleon_use_admonition_for_examples = False
-napoleon_use_admonition_for_notes = False
-napoleon_use_admonition_for_references = False
-napoleon_use_ivar = False
-napoleon_use_param = True
-napoleon_use_rtype = True
-napoleon_preprocess_types = False
-napoleon_type_aliases = None
-napoleon_attr_annotations = True
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

-intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/', None),
-    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
-}
-intersphinx_disabled_domains = ['std']
+extensions = ['sphinx.ext.linkcode',
+              'sphinx.ext.duration',
+              'sphinx.ext.coverage',
+              'sphinx.ext.napoleon',
+              'sphinx.ext.autodoc',
+              'sphinx_autodoc_typehints',
+              'sphinx_github_changelog',
+              'sphinx_rtd_size',
+              'sphinx.ext.mathjax',
+              'myst_nb'
+              ]

 templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

-# -- Options for HTML output
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

 html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

+# Resolve function for the linkcode extension.
 def linkcode_resolve(domain, info):
-    if domain != 'py':
-        return None
-    if not info['module']:
+    def find_source():
+        import inspect
+        import os, sys
+        obj = sys.modules[info["module"]]
+        for part in info["fullname"].split("."):
+            obj = getattr(obj, part)
+
+        fn = inspect.getsourcefile(obj)
+        fn = os.path.relpath(fn, start=os.path.dirname(__file__))
+        source, lineno = inspect.getsourcelines(obj)
+        return fn, lineno, lineno + len(source) - 1
+
+    if domain != "py" or not info["module"]:
        return None
-    filename = info['module'].replace('.', '/')
-    return "https://github.com/PhasesResearchLab/pyzentropy/blob/main/%s.py" % filename

-# -- Options for EPUB output
-epub_show_urls = 'footnote'
+    try:
+        rel_path, line_start, line_end = find_source()
+        # __file__ is imported from pyzentropy
+        filename = f"pyzentropy/{rel_path}#L{line_start}-L{line_end}"
+    except Exception:
+        # no need to be relative to core here as module includes full path.
+        filename = info["module"].replace(".", "/") + ".py"
+
+    tag = "v" + str(__version__)
+    return f"https://github.com/PhasesResearchLab/pyzentropy/blob/{tag}/{filename}"


The release/__version__ is hard-coded to 0.1.0, but the package version in pyproject.toml is 0.0.0. This will make the docs display the wrong version and will also generate linkcode URLs pointing at a tag (v0.1.0) that likely doesn’t exist for branch builds. Consider deriving the version from package metadata (e.g., importlib.metadata.version('pyzentropy')) and/or using the current branch (main) unless building a tagged release.

Copilot · 2026-02-06T21:54:00Z

pyzentropy/system.py

+            Helmholtz free energies :math:`F(T, V)`.
+        helmholtz_energies_dV:
+            First volume derivatives :math:`\partial F / \partial V`.
+        helmholtz_energies_d2V2:
+            Second volume derivatives :math:`\partial^2 F / \partial V^2`.


These docstring math roles include backslashes (e.g., \partial) inside a normal Python string literal. In Python this creates “invalid escape sequence” warnings (\p, \m, etc.) at import/compile time and can break doc builds when warnings are treated as errors. Use a raw docstring (r"""...""") or escape the backslashes (\\partial, \\mathrm, etc.) throughout the math expressions.

nhew1994 and others added 30 commits January 16, 2026 16:48

Merge pull request #18 from PhasesResearchLab/main

c813161

Update docs from main

Update documentation for pyzentropy.configuration

42e62d9

MAINT: improve docstrings and type hints for docs

1826764

MAINT: modify api structure for docs

ff5b713

MAINT: restructure api for docs

e732eac

FIX: rename rst file to the right name for docs

1f239ab

MAINT: improve type hints in format_plot

3306489

MAINT: add a bit more detail to Configuration docstrings

323d2f8

FIX: fix Configuration docstrings for docs

b3d852a

MAINT: remove unnecessary formulas from Configuration docstrings

ab1261c

MAINT: add more docstrings to plot_vt in Configuration

f3bb889

MAINT: remove redundant arg in docstring of Configuration

4da4549

MAINT: reformat docstrings for System

db4a2d4

MAINT: update System docstrings

24d5d5c

MAINT: update System docstrings

084eb95

MAINT: Remove unused loop index in partition function calculation

b304cbf

MAINT: update System docstrings

bca0841

MAINT: update System docstrings

e1e19ab

Improve math formatting for partition function

85fb605

Updated the math formatting for the partition function in the docstring.

Simplify partition function calculation description

207eadf

Removed detailed explanation of partition function calculation and simplified the description.

MAINT: remove unused loop index in __init__

828bf8f

MAINT: reformat docstrings in Configuration

f14be89

MAINT: update System docstrings

a568db8

MAINT: update System docstrings

58ff3ab

MAINT: update System docstrings

09dba82

MAINT: update Systems docstrings

163d482

MAINT: update System docstrings

58d5484

MAINT: update System docstrings

232d260

MAINT: update README

bcdf6dd

MAINT: remove type hints from docstrings

1b30358

DOCS: update Read the Docs content

bae30d8

nhew1994 requested a review from Copilot February 6, 2026 21:48

Copilot started reviewing on behalf of nhew1994 February 6, 2026 21:49 View session

Copilot AI reviewed Feb 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs#19

Docs#19
nhew1994 wants to merge 31 commits intomainfrom
docs

nhew1994 commented Feb 6, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments

Conversation

nhew1994 commented Feb 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments