Merge pull request #150 from openkim/docs

Fix readthedoc docs build

.readthedocs.yaml

@@ -4,18 +4,21 @@
 # Required
 version: 2
 
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-   configuration: docs/source/conf.py
+  configuration: docs/source/conf.py
 
 # Optionally build your docs in additional formats such as PDF
 formats:
-   - pdf
+  - pdf
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-   version: "3.10"
-   install:
-   - requirements: docs/requirements-docs.txt
-   - method: pip
-     path: .
+  install:
+    - requirements: docs/requirements-docs.txt

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-## v0.4.2 (2023/12/17)
+## v0.4.3 (2023/12/17)
 
 - Fix installing ptemcee
 

devtool/README.md

@@ -14,6 +14,8 @@
 
 - Update docs at `kliff/docs/source` as necessary
 
+- In docs, run `$ generate_api_docs.py` to generate API docs
+
 - Generate docs by running `$ make html` in the `kliff/docs` directory
 
   - Note, check the generated tutorial notebooks -- sometimes sphinx-galley will

docs/generate_api_docs.py

@@ -0,0 +1,102 @@
+import subprocess
+from pathlib import Path
+
+
+def get_all_modules(source: Path = "./kliff") -> list[str]:
+    """
+    Get all modules of the package.
+
+    Note, this only get the first-level modules like `kliff.module_a`, not modules
+    (in subpackages) like `kliff.subpackage_a.module_b`. subpackage is considered
+    as a module.
+
+    This takes advantage of
+        $ sphinx-apidoc -f -e -o <outdir> <sourcedir>
+    Return a list of modules names.
+    """
+    results = subprocess.run(
+        ["sphinx-apidoc", "-f", "-e", "-o", "/tmp/kliff_apidoc", source],
+        capture_output=True,
+    )
+    results = results.stdout.decode("utf-8")
+
+    modules = []
+    for line in results.split("\n"):
+        if "Creating" in line:
+            name = line.split("/")[-1].split(".")
+            if len(name) >= 4:
+                mod = name[1]
+                if mod not in modules:
+                    modules.append(mod)
+    return modules
+
+
+def autodoc_package(path: Path, modules: list[str]):
+    """
+    Create a package reference page.
+
+    Args:
+        path: directory to place the file
+        modules: list of API modules
+    """
+    path = Path(path).resolve()
+    if not path.exists():
+        path.mkdir(parents=True)
+
+    with open(path / "kliff.rst", "w") as f:
+        f.write(".. _reference:\n\n")
+        f.write("Package Reference\n")
+        f.write("=================\n\n")
+        f.write(".. toctree::\n")
+        for m in modules:
+            f.write("    kliff." + m + "\n")
+
+
+def autodoc_module(path: Path, module: str):
+    """
+    Create a module reference page.
+
+    Args:
+        path: directory to place the file
+        module: name of the module
+    """
+    path = Path(path).resolve()
+    if not path.exists():
+        path.mkdir(parents=True)
+
+    module_name = "kliff." + module
+    fname = path.joinpath(module_name + ".rst")
+    with open(fname, "w") as f:
+        f.write(f"{module_name}\n")
+        f.write("-" * len(module_name) + "\n\n")
+        f.write(f".. automodule:: {module_name}\n")
+        f.write("    :members:\n")
+        f.write("    :undoc-members:\n")
+        # f.write("    :show-inheritance:\n")
+        f.write("    :inherited-members:\n")
+
+
+def create_apidoc(directory: Path = "./apidoc"):
+    """
+    Create API documentation, a separate page for each module.
+
+    Args:
+        directory:
+    """
+
+    # modules with the below names will not be excluded
+    excludes = ["cmdline"]
+
+    package_path = Path(__file__).parents[2] / "kliff"
+    modules = get_all_modules(package_path)
+    for exc in excludes:
+        modules.remove(exc)
+    modules = sorted(modules)
+
+    autodoc_package(directory, modules)
+    for mod in modules:
+        autodoc_module(directory, mod)
+
+
+if __name__ == "__main__":
+    create_apidoc(directory="./source/apidoc")

docs/requirements-docs.txt

@@ -0,0 +1,7 @@
+sphinx
+furo
+sphinx-gallery
+sphinx-autodoc-typehints
+matplotlib
+myst-nb
+sphinx-copybutton

docs/source/conf.py

@@ -12,8 +12,6 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 import os
 import sys
-import subprocess
-from pathlib import Path
 
 
 # sys.path.insert(0, os.path.abspath('.'))
@@ -235,107 +233,3 @@
 
 # -- myst-nb -----------------------------------------------------------------
 nb_execution_timeout = 120
-
-# -- generate api doc ----------------------------------------------------------
-
-
-def get_all_modules(source: Path = "./kliff") -> list[str]:
-    """
-    Get all modules of the package.
-
-    Note, this only get the first-level modules like `kliff.module_a`, not modules
-    (in subpackages) like `kliff.subpackage_a.module_b`. subpackage is considered
-    as a module.
-
-    This takes advantage of
-        $ sphinx-apidoc -f -e -o <outdir> <sourcedir>
-    Return a list of modules names.
-    """
-    results = subprocess.run(
-        ["sphinx-apidoc", "-f", "-e", "-o", "/tmp/kliff_apidoc", source],
-        capture_output=True,
-    )
-    results = results.stdout.decode("utf-8")
-
-    modules = []
-    for line in results.split("\n"):
-        if "Creating" in line:
-            name = line.split("/")[-1].split(".")
-            if len(name) >= 4:
-                mod = name[1]
-                if mod not in modules:
-                    modules.append(mod)
-    return modules
-
-
-def autodoc_package(path: Path, modules: list[str]):
-    """
-    Create a package reference page.
-
-    Args:
-        path: directory to place the file
-        modules: list of API modules
-    """
-    path = Path(path).resolve()
-    if not path.exists():
-        path.mkdir(parents=True)
-
-    with open(path / "kliff.rst", "w") as f:
-        f.write(".. _reference:\n\n")
-        f.write("Package Reference\n")
-        f.write("=================\n\n")
-        f.write(".. toctree::\n")
-        for m in modules:
-            f.write("    kliff." + m + "\n")
-
-
-def autodoc_module(path: Path, module: str):
-    """
-    Create a module reference page.
-
-    Args:
-        path: directory to place the file
-        module: name of the module
-    """
-    path = Path(path).resolve()
-    if not path.exists():
-        path.mkdir(parents=True)
-
-    module_name = "kliff." + module
-    fname = path.joinpath(module_name + ".rst")
-    with open(fname, "w") as f:
-        f.write(f"{module_name}\n")
-        f.write("-" * len(module_name) + "\n\n")
-        f.write(f".. automodule:: {module_name}\n")
-        f.write("    :members:\n")
-        f.write("    :undoc-members:\n")
-        # f.write("    :show-inheritance:\n")
-        f.write("    :inherited-members:\n")
-
-
-def create_apidoc(directory: Path = "./apidoc"):
-    """
-    Create API documentation, a separate page for each module.
-
-    Args:
-        directory:
-
-    Returns:
-
-    """
-
-    # modules with the below names will not be excluded
-    excludes = ["cmdline"]
-
-    package_path = Path(__file__).parents[2] / "kliff"
-    modules = get_all_modules(package_path)
-    for exc in excludes:
-        modules.remove(exc)
-    modules = sorted(modules)
-
-    autodoc_package(directory, modules)
-    for mod in modules:
-        autodoc_module(directory, mod)
-
-
-create_apidoc(directory="./apidoc")

docs/source/installation.rst

@@ -7,8 +7,8 @@ Installation
 
 KLIFF can be installed via package managers (conda or pip) or from source.
 
-Conda
------
+Installing KLIFF
+================
 This recommended way to install KLIFF is via conda. You can install it by:
 
 .. code-block:: bash