Added documentation

h-0-0 · Dec 2, 2023 · 481f939 · 481f939
1 parent 10a48b8
commit 481f939
Show file tree

Hide file tree

Showing 22 changed files with 6,936 additions and 13 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,50 @@
+name: website
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+    # Alternative: only build for tags.
+    # tags:
+    #   - '*'
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      # ADJUST THIS: install all dependencies (including pdoc)
+      - run: pip install -e .
+      - run: pip install pdoc
+      # ADJUST THIS: build your documentation into docs/.
+      # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
+      - run: pdoc --docformat google -o docs/.html src
+
+      - uses: actions/upload-pages-artifact@v2
+        with:
+          path: docs/
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v2
diff --git a/CLASSDESIGN.md b/CLASSDESIGN.md
@@ -0,0 +1,14 @@
+# Class Design
+Here we will outline the different kind of classes that are used in slune and how they interact with each other. There are 3 types:
+- 'Searcher' classes - these are the classes that are used to define and traverse a search space.
+- 'Logger' classes - these are the classes that are used to create and read log files.
+- 'Saver' classes - these are the classes that are used to save logs to files and read logs from files.
+
+The base module is where the base classes for each of these types are defined. The base classes are:
+- BaseSearcher
+- BaseLogger
+- BaseSaver
+
+To create a new searcher, logger or saver, you must inherit from the appropriate base class and implement the required methods. The required methods will have the '@abc.abstractmethod' decorator above them and will throw errors if they are not implemented. The compulsory methods allow for well-defined interactions between the different classes and should allow for any combination of searcher, logger and saver to be used together. 
+
+Please read the docs for the base classes to see what methods are required to be implemented and how they should be implemented.
diff --git a/README.md b/README.md
@@ -1,3 +1,4 @@
+![PyPI - Version](https://img.shields.io/pypi/v/:slune-lib)
 [![license](https://img.shields.io/badge/License-MIT-purple.svg)](LICENSE)
 ![badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/h-0-0/4aa01e058fee448070c587f6967037e4/raw/CodeCovSlune.json)
 
@@ -111,7 +112,6 @@ Please check out the examples folder for notebooks detailing in more depth some
 
 ## Roadmap
 - Make package user friendly:
-    - Add documentation.
     - Go through automation settings.
     - Code of conduct.
     - Contributing guidelines.

diff --git a/docs/.html/index.html b/docs/.html/index.html
@@ -0,0 +1,7 @@
+<!doctype html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./src.html"/>
+</head>
+</html>
diff --git a/docs/.html/search.js b/docs/.html/search.js
diff --git a/docs/.html/src.html b/docs/.html/src.html
diff --git a/docs/.html/src/slune.html b/docs/.html/src/slune.html
diff --git a/docs/.html/src/slune/base.html b/docs/.html/src/slune/base.html
diff --git a/docs/.html/src/slune/loggers.html b/docs/.html/src/slune/loggers.html
diff --git a/docs/.html/src/slune/loggers/default.html b/docs/.html/src/slune/loggers/default.html
diff --git a/docs/.html/src/slune/savers.html b/docs/.html/src/slune/savers.html
diff --git a/docs/.html/src/slune/savers/csv.html b/docs/.html/src/slune/savers/csv.html
diff --git a/docs/.html/src/slune/searchers.html b/docs/.html/src/slune/searchers.html
diff --git a/docs/.html/src/slune/searchers/grid.html b/docs/.html/src/slune/searchers/grid.html
diff --git a/docs/.html/src/slune/slune.html b/docs/.html/src/slune/slune.html
diff --git a/docs/.html/src/slune/utils.html b/docs/.html/src/slune/utils.html
diff --git a/src/__init__.py b/src/__init__.py
@@ -1 +1,4 @@
-# Empty
+"""
+.. include:: ../README.md
+.. include:: ../CLASSDESIGN.md
+"""
diff --git a/src/slune/__init__.py b/src/slune/__init__.py
@@ -1,11 +1,14 @@
 # from .slune import submit_job, sbatchit
 # __all__ = ['slune', 'base', 'utils', 'loggers', 'savers', 'searchers' ]
 
-from .searchers import grid
-from .savers import csv
-from .loggers import default
+from .searchers import *
+from .savers import *
+from .loggers import *
 from .slune import submit_job, sbatchit, lsargs, garg, get_csv_slog
 from . import base, utils
 
-__all__ = ['submit_job', 'sbatchit', 'lsargs', 'garg', 'get_csv_slog',
-           'base', 'utils', 'default', 'grid', 'csv']
+# __all__ = ['submit_job', 'sbatchit', 'lsargs', 'garg', 'get_csv_slog',
+        #    'base', 'utils', 'default', 'grid', 'csv']
+
+import importlib.metadata
+__version__ = importlib.metadata.version("slune-lib")
diff --git a/src/slune/loggers/__init__.py b/src/slune/loggers/__init__.py
@@ -1,3 +1,3 @@
 from .default import LoggerDefault
 
-__all__ = ['LoggerDefault']
+# __all__ = ['LoggerDefault']
diff --git a/src/slune/savers/__init__.py b/src/slune/savers/__init__.py
@@ -1,3 +1,3 @@
 from .csv import SaverCsv
 
-__all__ = ['SaverCsv']
+# __all__ = ['SaverCsv']
diff --git a/src/slune/searchers/__init__.py b/src/slune/searchers/__init__.py
@@ -1,3 +1,3 @@
 from .grid import SearcherGrid
 
-__all__ = ['SearcherGrid']
+# __all__ = ['SearcherGrid']
diff --git a/src/slune/slune.py b/src/slune/slune.py
@@ -1,5 +1,5 @@
 from typing import List, Optional, Union
-from slune.base import Searcher, Saver
+from slune.base import BaseSearcher, BaseSaver
 import subprocess
 import sys
 from slune.savers.csv import SaverCsv
@@ -22,7 +22,7 @@ def submit_job(sh_path: str, args: List[str]):
     except subprocess.CalledProcessError as e:
         print(f"Error running sbatch: {e}")
 
-def sbatchit(script_path: str, sbatch_path: str, searcher: Searcher, cargs: Optional[List]=[], saver: Optional[Saver]=None):
+def sbatchit(script_path: str, sbatch_path: str, searcher: BaseSearcher, cargs: Optional[List]=[], saver: Optional[BaseSaver]=None):
     """ Submits jobs based on arguments given by searcher.
 
     For each job runs the script stored at script_path with selected parameter values given by searcher
@@ -91,7 +91,7 @@ def single_garg(arg_name):
     else:
         return single_garg(arg_names)
 
-def get_csv_slog(params: Optional[dict]= None, root_dir: Optional[str]='slune_results') -> Saver:
+def get_csv_slog(params: Optional[dict]= None, root_dir: Optional[str]='slune_results') -> BaseSaver:
     """ Returns a SaverCsv object with the given parameters and root directory.
 
     Args: