Merge pull request #3 from EQuS/back-to-mkdocs

moving back to mkdocs material

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci 
+on:
+  push:
+    branches:
+      - master 
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

README.md

@@ -47,44 +47,39 @@ If you intend to contribute to this project, please install `jaxquantum` in edit
 ```bash
 git clone git@github.com:EQuS/jaxquantum.git jaxquantum
 cd jaxquantum
-pip install -e .[dev]
+pip install -e .[dev, docs]
 ```
 
-Please use `pip install -e '.[dev]'` if you are a `zsh` user.
+Please use `pip install -e '.[dev, docs]'` if you are a `zsh` user.
 
 Installing the package in the usual non-editable mode would require a developer to upgrade their pip installation (i.e. run `pip install --upgrade .`) every time they update the package source code.
 
 ## Documentation
 
 Documentation should be viewable here: [https://github.com/pages/EQuS/jaxquantum/](https://github.com/pages/EQuS/jaxquantum/) 
 
-#### View locally
+### Build and view locally
 
+To view documentation locally, plesae make sure the install the requirements under the `docs` extra, as specified above. Then, run the following:
 
-To view documentation locally, please open `docs/build/html/index.html` in your browser.
+```
+mkdocs serve
+```
 
+The documentation should now be at the url provided by the above command. 
 
-#### Build documentation 
+### Updating Docs
 
-To rebuild documentation, please start in the root folder and run:
+The documentation should be updated automatically when any changes are made to the `main` branch. However, updates can also be forced by running:
 
-```sh
-cd docs
-make clean
-make html
 ```
-
-For windows users, you may have to do:
-```sh
-.\make.bat clean
-.\make.bat html
+mkdocs gh-deploy --force
 ```
-
-*You may also have to delete the `docs/source/_autosummary` directory before running the above commands.*
+This will build your documentation and deploy it to a branch gh-pages in your repository.
 
 ## Acknowledgements
 
-**Core Devs:** [Shantanu Jha](https://github.com/Phionx)
+**Core Devs:** [Shantanu Jha](https://github.com/Phionx), [Shoumik Chowdhury](https://github.com/shoumikdc)
 
 
 This package was developed while conducting research in the Engineering Quantum Systems Group at MIT with invaluable advice from [Prof. William D. Oliver](https://equs.mit.edu/william-d-oliver/). 

docs/gen_ref_pages.py

@@ -0,0 +1,32 @@
+"""Generate the code reference pages."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+for path in sorted(Path("jaxquantum").rglob("*.py")):
+    module_path = path.relative_to(".").with_suffix("")
+    doc_path = path.relative_to(".").with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = list(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = str(doc_path)
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        identifier = ".".join(parts)
+        print("::: " + identifier, file=fd)
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("reference/summary.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/index.md

@@ -0,0 +1,6 @@
+# Welcome to jaxquantum
+
+`jaxquantum` leverages JAX to enable the auto differentiable and accelerated simulation of quantum dynamical systems, through tooling such as master equation solving. 
+
+
+*More docs are comming soon!*