Add docs with auto API reference generation when pushed to main. (#109)

* Add initial mkdocs * Add mkdocs CI * Update CI * Change lighter color scheme * Set md-nav to correct color in slate * Update docs [WIP] * Update projects * Add docs publishing workflow * Make docs-publish triggered by pushes on `main' * Fix typo in docs (MyXRayDataset) * Add info on docs contributions * Add auto API reference generation * Add list of submodules and py to each module, move version and logging * Update README * Update README * Update lighter/utils/dynamic_imports.py Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update lighter/utils/runner.py Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update docs/overrides/components/navigation-links3.css Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update docstrings and reference generation * Fix module type hint --------- Co-authored-by: Suraj Pai <[email protected]> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
project-lighter · Mar 26, 2024 · 2e8a27d · 2e8a27d
1 parent 8b5e7ed
commit 2e8a27d
Show file tree

Hide file tree

Showing 64 changed files with 3,629 additions and 110 deletions.
diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml
@@ -0,0 +1,28 @@
+name: Docs Publish
+on:
+  push:
+    branches:
+      - 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 mkdocs-autorefs mkdocstrings
+      - run: mkdocs gh-deploy --force
diff --git a/.gitignore b/.gitignore
@@ -150,3 +150,5 @@ projects/*
 !projects/README.md
 !projects/cifar10
 **/predictions/
+*/.DS_Store
+.DS_Store
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,4 +1,17 @@
-# How to contribute
+1. [Code contribution](#code-contribution)
+   - [Dependencies](#dependencies)
+   - [Codestyle](#codestyle)
+     - [Checks](#checks)
+       - [Before submitting](#before-submitting)
+   - [Other help](#other-help)
+
+2. [Documentation contribution](#documentation-contribution)
+   - [Dependencies](#dependencies-1)
+    - [Serving the documentation locally](#serving-the-documentation-locally)
+    - [Deploying the documentation to GitHub Pages](#deploying-the-documentation-to-github-pages)
+
+
+# Code contribution
 
 ## Dependencies
 
@@ -45,3 +58,28 @@ You can contribute by spreading a word about this library.
 It would also be a huge contribution to write
 a short article on how you are using this project.
 You can also share your best practices with us.
+
+
+# Documentation contribution
+Our documentation is located in the `docs/` folder and is built using `mkdocs` and `mkdocs-material`.
+
+The API reference is generated automatically from the docstrings in the code using `mkdocstrings`. Our docstrings follow the `google` style.
+
+##  Dependencies
+To install `mkdocs-material` together with the required dependencies run:
+
+```bash
+pip install mkdocs-material mkdocs-autorefs mkdocstrings mkdocs-gen-files mkdocs-literate-nav mkdocs-section-index
+```
+
+## Serving the documentation locally
+While working on the documentation, you can serve it locally to see the changes in real-time.
+
+```bash
+cd docs/
+mkdocs serve
+```
+
+## Deploying the documentation to GitHub Pages
+
+The documentation is automatically deployed once the changes are merged into the `main` branch.
diff --git a/README.md b/README.md
@@ -1,8 +1,11 @@
 <div align="center">
 <picture>
+  <!-- old code that allows different pics for light/dark mode -->
+  <!--
   <source media="(prefers-color-scheme: dark)" srcset="./assets/images/lighter_dark.png">
   <source media="(prefers-color-scheme: light)" srcset="./assets/images/lighter_light.png">
-  <img align="center" alt="Lighter logo" src="h/assets/images/lighter_dark.png">
+   -->
+  <img align="center" alt="Lighter logo" src="./assets/images/lighter.png">
 </picture>
 </div>
 <br/>
@@ -12,35 +15,47 @@
 </div>
 
 
-Welcome to `lighter`, an elegant and powerful wrapper for [PyTorch Lightning](https://github.com/Lightning-AI/lightning) that simplifies the way you build and manage your deep learning experiments. Unleash your model's potential through a unified, **configuration-based** approach that streamlines the experimentation process, empowering both beginners and experts in the field.
+With `lighter`, focus on your deep learning experiments and forget about boilerplate through:
+ 1. **Task-agnostic** training logic already implemented for you (classification, segmentation, self-supervised, etc.)
+ 2. **Configuration-based** approach that will ensure that you can always reproduce your experiments and know what hyperparameters you used.
+ 3. Extremely **simple integration of custom** models, datasets, transforms, or any other components to your experiments.
+
+&nbsp;
+
+`lighter` stands on the shoulder of these two giants:
+ - [MONAI Bundle](https://docs.monai.io/en/stable/bundle_intro.html) - Configuration system. Similar to [Hydra](https://github.com/facebookresearch/hydra), but with additional features.
+ - [PyTorch Lightning](https://github.com/Lightning-AI/lightning) - Our [`LighterSystem`](https://project-lighter.github.io/lighter/reference/system/) is based on the PyTorch Lightning [`LightningModule`](https://lightning.ai/docs/pytorch/stable/common/lightning_module.html) and implements all the necessary training logic for you. Couple it with the PyTorch Lightning [Trainer](https://lightning.ai/docs/pytorch/stable/common/trainer.html) and you're good to go.
+
+Simply put, `lighter = config(trainer + system)` 😇
 
 
 ## 📖 Usage
 
-- [Documentation](https://project-lighter.github.io/lighter/)
+- [📚 Documentation](https://project-lighter.github.io/lighter/)
+- [🎥 YouTube Channel](https://www.youtube.com/channel/UCef1oTpv2QEBrD2pZtrdk1Q)
 
 ## 🚀 Install
 
 Current release:
-````
+```bash
 pip install project-lighter
-````
+```
 
 Pre-release (up-to-date with the main branch):
-````
+```bash
 pip install project-lighter --pre
-````
+```
 
 For development:
-````
+```bash
 make setup
 make install             # Install lighter via Poetry
 make pre-commit-install  # Set up the pre-commit hook for code formatting
 poetry shell             # Once installed, activate the poetry shell
-````
+```
 
 ## 💡 Projects
-List of projects that use `lighter`:
+Projects that use `lighter`:
 
 | Project | Description |
 | --- | --- |
@@ -49,7 +64,7 @@ List of projects that use `lighter`:
 
 ## 📄 Cite:
 
-If you find `lighter` useful in your research or project, please consider citing it. Here's an example BibTeX citation entry:
+If you find `lighter` useful in your research or project, please consider citing it:
 
 ```bibtex
 @software{lighter,

diff --git a/assets/images/lighter.png b/assets/images/lighter.png
diff --git a/assets/images/lighter_dark.png b/assets/images/lighter_dark.png
diff --git a/assets/images/lighter_light.png b/assets/images/lighter_light.png
diff --git a/docs/advanced/callbacks.md b/docs/advanced/callbacks.md
@@ -0,0 +1 @@
+🚧 Under construction 🚧
diff --git a/docs/advanced/inferer.md b/docs/advanced/inferer.md
@@ -0,0 +1 @@
+🚧 Under construction 🚧
diff --git a/docs/advanced/postprocessing.md b/docs/advanced/postprocessing.md
@@ -0,0 +1 @@
+🚧 Under construction 🚧
diff --git a/docs/assets/extra.css b/docs/assets/extra.css
@@ -0,0 +1,29 @@
+[data-md-color-scheme="default"] {
+    --md-primary-fg-color:   #459AA3;
+    --md-accent-fg-color:    #459AA3;
+    color:                   #14181e;
+  }
+
+[data-md-color-scheme="slate"] {
+    --md-primary-fg-color:   #459AA3;
+    --md-accent-fg-color:    #459AA3;
+    --md-default-bg-color:   #14181e;
+}
+[data-md-color-scheme="slate"] .md-nav {
+    --md-typeset-a-color: #459AA3;
+}
+
+@media only screen and (min-width: 75.25em) {
+  .md-main__inner {
+    max-width: 1000em;
+  }
+  .md-sidebar--primary {
+    left: 0;
+  }
+  .md-sidebar--secondary {
+    right: 0;
+    margin-left: 0em;
+    -webkit-transform: none;
+    transform: none;   
+  }
+}
diff --git a/docs/assets/images/Lighter_demo.png b/docs/assets/images/Lighter_demo.png
diff --git a/docs/assets/images/PL_demo.png b/docs/assets/images/PL_demo.png
diff --git a/docs/assets/images/lighter_banner.png b/docs/assets/images/lighter_banner.png
diff --git a/docs/assets/images/lighter_favicon.png b/docs/assets/images/lighter_favicon.png
diff --git a/docs/assets/images/lighter_logo.png b/docs/assets/images/lighter_logo.png