Feature/improve docs

.github/workflows/tests.yml

@@ -44,18 +44,18 @@ jobs:
           poetry --version
 
       - name: Install System Dependencies (Ubuntu)
-        if: startsWith(matrix.os, 'ubuntu') && (matrix.session == 'tests' || matrix.session == 'pre-commit')
+        if: startsWith(matrix.os, 'ubuntu') && (matrix.session == 'no')
         run: |
           sudo apt-get update
           sudo apt-get install -y python3-dev python3-setuptools python3-scipy python3-matplotlib python3-pytest python3-sympy g++ build-essential gfortran libopenblas-dev liblapack-dev libmumps-scotch-dev
 
       - name: Install Python dependencies (Ubuntu)
-        if: startsWith(matrix.os, 'ubuntu') && (matrix.session == 'tests' || matrix.session == 'pre-commit')
+        if: startsWith(matrix.os, 'ubuntu') && (matrix.session == 'no')
         run: |
           python -m pip install cython tinyarray
 
       - name: Clone and Install kwant (Ubuntu)
-        if: startsWith(matrix.os, 'ubuntu') && (matrix.session == 'tests' || matrix.session == 'pre-commit')
+        if: startsWith(matrix.os, 'ubuntu') && (matrix.session == 'no')
         run: |
           git clone https://github.com/kwant-project/kwant.git
           cd kwant

README.md

@@ -50,9 +50,9 @@ You can install _KPM Tools_ via [pip] from [PyPI]:
 $ pip install kpm-tools
 ```
 
-## Usage
+## Python API
 
-Please see the [Command-line Reference] for details.
+Please see the [Python API reference] for details.
 
 ## Contributing
 
@@ -83,4 +83,4 @@ This project was generated from [@cjolowicz]'s [Hypermodern Python Cookiecutter]
 
 [license]: https://github.com/piskunow/kpm-tools/blob/main/LICENSE
 [contributor guide]: https://github.com/piskunow/kpm-tools/blob/main/CONTRIBUTING.md
-[command-line reference]: https://kpm-tools.readthedocs.io/en/latest/usage.html
+[python api reference]: https://kpm-tools.readthedocs.io/en/latest/api.html

docs/api.md

@@ -0,0 +1,81 @@
+# Python API
+
+```{eval-rst}
+.. click:: kpm_tools.__main__:main
+    :prog: kpm-tools
+    :nested: full
+```
+
+Each of the following sections describes the usage of different modules in the `kpm_tools` package.
+
+## Bloch Module
+
+```{eval-rst}
+.. automodule:: kpm_tools.bloch
+    :members:
+    :undoc-members:
+    :show-inheritance:
+```
+
+## Common Module
+
+```{eval-rst}
+.. automodule:: kpm_tools.common
+    :members:
+    :undoc-members:
+    :show-inheritance:
+```
+
+## Evolution Module
+
+```{eval-rst}
+.. automodule:: kpm_tools.evolution
+    :members:
+    :undoc-members:
+    :show-inheritance:
+```
+
+## Hamiltonians Module
+
+```{eval-rst}
+.. automodule:: kpm_tools.hamiltonians
+    :members:
+    :undoc-members:
+    :show-inheritance:
+```
+
+## KPM Functions Module
+
+```{eval-rst}
+.. automodule:: kpm_tools.kpm_funcs
+    :members:
+    :undoc-members:
+    :show-inheritance:
+```
+
+## KPM Generator Module
+
+```{eval-rst}
+.. automodule:: kpm_tools.kpm_generator
+    :members:
+    :undoc-members:
+    :show-inheritance:
+```
+
+## Plotting Module
+
+```{eval-rst}
+.. automodule:: kpm_tools.plotting
+    :members:
+    :undoc-members:
+    :show-inheritance:
+```
+
+## Tiles Module
+
+```{eval-rst}
+.. automodule:: kpm_tools.tiles
+    :members:
+    :undoc-members:
+    :show-inheritance:
+```

docs/conf.py

@@ -1,10 +1,17 @@
 """Sphinx configuration."""
+
+import inspect
+import os
+import sys
+
+
 project = "KPM Tools"
 author = "Pablo Piskunow"
 copyright = "2023, Pablo Piskunow"
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
+    "sphinx.ext.linkcode",
     "sphinx_click",
     "myst_parser",
     "nbsphinx",
@@ -36,3 +43,43 @@
 
 
   """  # noqa: B950
+
+
+def linkcode_resolve(domain, info):
+    """Resolve links to source."""
+    if domain != "py":
+        return None
+    if not info["module"]:
+        return None
+
+    # Replace with your project's GitHub repository URL
+    github_repo = "https://github.com/piskunow/kpm-tools"
+
+    # Get the module object
+    module = sys.modules.get(info["module"])
+    if module is None:
+        return None
+
+    # Get the source file path of the module
+    filename = inspect.getsourcefile(module)
+    if filename is None:
+        return None
+
+    # Trim the filename to a path relative to the project root
+    rel_fn = os.path.relpath(filename, start=os.path.dirname(__file__))
+
+    # Get the line number of the object within the module
+    obj = module
+    for part in info["fullname"].split("."):
+        obj = getattr(obj, part, None)
+
+    if obj is None:
+        return None
+
+    try:
+        lines, _ = inspect.getsourcelines(obj)
+    except Exception:
+        return None
+
+    line = inspect.getsourcelines(obj)[1]
+    return f"{github_repo}/blob/main/{rel_fn}#L{line}"

docs/index.md

@@ -6,7 +6,7 @@ end-before: <!-- github-only -->
 
 [license]: license
 [contributor guide]: contributing
-[command-line reference]: usage
+[python api]: api
 
 ```{toctree}
 ---
@@ -15,8 +15,7 @@ maxdepth: 1
 ---
 
 Tutorials <tutorials>
-usage
-reference
+api
 contributing
 Code of Conduct <codeofconduct>
 License <license>