Update spin docs (#6387)

**Context:**
This PR updates the spin function docs for uniformity and consistency.
[sc-75955]

doc/code/qml_spin.rst

@@ -4,12 +4,43 @@ qml.spin
 Overview
 --------
 
-This module contains functions and classes for creating and manipulating Hamiltonians for the spin models.
+This module contains functions and classes for creating and manipulating Hamiltonians for
+spin models.
+
+Hamiltonian functions
+^^^^^^^^^^^^^^^^^^^^^
+
+.. currentmodule:: pennylane.spin
+
+.. autosummary::
+    :toctree: api
+
+    ~emery
+    ~fermi_hubbard
+    ~haldane
+    ~heisenberg
+    ~kitaev
+    ~transverse_ising
+
+
+Hamiltonian custom functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. currentmodule:: pennylane.spin
 
-.. automodapi:: pennylane.spin
-    :no-heading:
-    :no-main-docstr:
-    :skip: Lattice
-    :include-all-objects:
+.. autosummary::
+    :toctree: api
+
+    ~spin_hamiltonian
+
+
+Lattice classes and functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. currentmodule:: pennylane.spin
+
+.. autosummary::
+    :toctree: api
+
+    ~Lattice
+    ~generate_lattice

doc/releases/changelog-dev.md

@@ -298,6 +298,9 @@
 
 <h3>Documentation 📝</h3>
 
+* Updated `qml.spin` documentation.
+  [(#6387)](https://github.com/PennyLaneAI/pennylane/pull/6387)
+
 * Updated links to PennyLane.ai in the documentation to use the latest URL format, which excludes the `.html` prefix.
   [(#6412)](https://github.com/PennyLaneAI/pennylane/pull/6412)
 
@@ -411,6 +414,7 @@ Lillian M. A. Frederiksen,
 Pietropaolo Frisoni,
 Emiliano Godinez,
 Austin Huang,
+Soran Jahangiri,
 Jacob Kitchen,
 Korbinian Kottmann,
 Christina Lee,

pennylane/spin/__init__.py

@@ -15,7 +15,7 @@
 This module provides the functionality to create spin Hamiltonians.
 """
 
-from .lattice import Lattice
+from .lattice import Lattice, generate_lattice
 from .spin_hamiltonian import (
     emery,
     fermi_hubbard,

pennylane/spin/lattice.py

@@ -67,11 +67,10 @@ class Lattice:
 
     **Example**
 
-    >>> n_cells = [2,2]
+    >>> n_cells = [2, 2]
     >>> vectors = [[0, 1], [1, 0]]
     >>> boundary_condition = [True, False]
-    >>> lattice = qml.spin.Lattice(n_cells, vectors,
-    >>>           boundary_condition=boundary_condition)
+    >>> lattice = qml.spin.Lattice(n_cells, vectors, boundary_condition=boundary_condition)
     >>> lattice.edges
     [(2, 3, 0), (0, 2, 0), (1, 3, 0), (0, 1, 0)]
 
@@ -358,21 +357,59 @@ def add_edge(self, edge_indices):
             self.edges.append(new_edge)
 
 
-def _generate_lattice(lattice, n_cells, boundary_condition=False, neighbour_order=1):
-    r"""Generates the lattice object for a given shape and n_cells.
+def generate_lattice(lattice, n_cells, boundary_condition=False, neighbour_order=1):
+    r"""Generates a :class:`~pennylane.spin.Lattice` object for a given lattice shape and number of
+    cells.
 
     Args:
-        lattice (str): Shape of the lattice. Input values can be ``'chain'``, ``'square'``, ``'rectangle'``,
-              ``'honeycomb'``, ``'triangle'``, ``'kagome'``, ``'lieb'``, ``'cubic'``, ``'bcc'``, ``'fcc'``,
-               or ``'diamond'``.
+        lattice (str): Shape of the lattice. Input values can be ``'chain'``, ``'square'``,
+            ``'rectangle'``, ``'triangle'``, ``'honeycomb'``,  ``'kagome'``, ``'lieb'``,
+            ``'cubic'``, ``'bcc'``, ``'fcc'`` or ``'diamond'``.
         n_cells (list[int]): Number of cells in each direction of the grid.
         boundary_condition (bool or list[bool]): Defines boundary conditions in different lattice axes.
-                               Default is ``False`` indicating open boundary condition.
+            Default is ``False`` indicating open boundary condition.
         neighbour_order (int): Specifies the interaction level for neighbors within the lattice.
-                               Default is 1, indicating nearest neighbour.
+            Default is 1, indicating nearest neighbour.
 
     Returns:
-        lattice object.
+        ~pennylane.spin.Lattice: lattice object.
+
+    **Example**
+
+    >>> shape = 'square'
+    >>> n_cells = [2, 2]
+    >>> boundary_condition = [True, False]
+    >>> lattice = qml.spin.generate_lattice(shape, n_cells, boundary_condition)
+    >>> lattice.edges
+    [(2, 3, 0), (0, 2, 0), (1, 3, 0), (0, 1, 0)]
+
+    .. details::
+        :title: Lattice details
+
+        The following lattice shapes are currently supported.
+
+        * ``'chain'``: linear arrangement of sites in one dimension
+
+        * ``'square'``: square arrangement of sites in two dimensions
+
+        * ``'rectangle'``: rectangular arrangement of sites in two dimensions
+
+        * ``'triangle'``: triangular arrangement of sites in two dimensions [`Phys. Rev. B 7, 5017 (1973) <https://journals.aps.org/pr/abstract/10.1103/PhysRev.79.357>`_]
+
+        * ``'honeycomb'``: `honeycomb <https://en.wikipedia.org/wiki/Hexagonal_lattice#Honeycomb_point_set>`_ arrangement of sites in two dimensions
+
+        * ``'kagome'``: kagome arrangement of sites in two dimensions [`Prog. Theor. Phys. 6, 306 (1951) <https://academic.oup.com/ptp/article/6/3/306/1852171>`_]
+
+        * ``'lieb'``: Lieb arrangement of sites in two dimensions [`arXiv:1004.5172 <https://arxiv.org/abs/1004.5172>`_]
+
+        * ``'cubic'``: `cubic <https://en.wikipedia.org/wiki/Cubic_crystal_system>`_ arrangement of sites in three dimensions
+
+        * ``'bcc'``: `body-centered cubic <https://en.wikipedia.org/wiki/Cubic_crystal_system>`_ arrangement of sites in three dimensions
+
+        * ``'fcc'``: `face-centered cubic <https://en.wikipedia.org/wiki/Cubic_crystal_system>`_ arrangement of sites in three dimensions
+
+        * ``'diamond'``: `diamond <https://en.wikipedia.org/wiki/Diamond_cubic>`_ arrangement of sites in three dimensions
+
     """
 
     lattice_shape = lattice.strip().lower()