Add dynamic generation script for markdown files

spencerwooo · Dec 13, 2024 · f6fa633 · f6fa633
1 parent 9d728f3
commit f6fa633
Show file tree

Hide file tree

Showing 11 changed files with 109 additions and 22 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <div align="center">
-  <div><img src="https://github.com/user-attachments/assets/6e94a09e-557e-4705-a80d-f1ca90a23421" alt="torchattack banner" width="640" /></div>
+  <div><img src="docs/images/torchattack.png" alt="torchattack banner" width="600" /></div>
 
   <a href="https://github.com/astral-sh/ruff">
     <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json" alt="Ruff">

diff --git a/docs/.pages b/docs/.pages
diff --git a/docs/attacks/fgsm.md b/docs/attacks/fgsm.md
diff --git a/docs/attacks/mifgsm.md b/docs/attacks/mifgsm.md
diff --git a/docs/development.md b/docs/development.md
@@ -4,38 +4,46 @@ uv is used for development.
 
 First, [install uv](https://docs.astral.sh/uv/getting-started/installation/).
 
+## Installing Dependencies
+
 Next, install dev dependencies.
 
 ```shell
 uv sync --dev
 ```
 
+### Installing Test Dependencies
+
 Install dependency group `test` to run tests.
 
 ```shell
 uv sync --dev --group test
 ```
 
+### Installing Documentation Dependencies
+
 Install dependency group `docs` to build documentation.
 
 ```shell
 uv sync --dev --group docs
 ```
 
-Install dependency group `test` to run tests.
-
-```shell
-uv sync --dev --group test
-```
+### Installing All Dependencies
 
 To install everything, run:
 
 ```shell
 uv sync --all-groups
 ```
 
+## Running Tests
+
 To run tests:
 
 ```shell
 pytest torchattack
 ```
+
+## Additional Information
+
+For more details on using uv, refer to the [uv documentation](https://docs.astral.sh/uv/).
diff --git a/docs/images/torchattack.png b/docs/images/torchattack.png
diff --git a/docs/index.md b/docs/index.md
@@ -2,9 +2,20 @@
 title: Home
 hide:
   - navigation
-  - toc
+  - footer
 ---
 
+<style>
+  .md-typeset h1,
+  .md-content__button {
+    display: none;
+  }
+</style>
+
+<figure markdown="1">
+![torchattack](./images/torchattack.png){: style="width:600px"}
+</figure>
+
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![pypi python versions](https://img.shields.io/pypi/pyversions/torchattack.svg?labelColor=2D3339)](https://pypi.python.org/pypi/torchattack)
 [![pypi version](https://img.shields.io/pypi/v/torchattack.svg?labelColor=2D3339)](https://pypi.python.org/pypi/torchattack)
@@ -17,8 +28,20 @@ _A curated list of adversarial attacks in PyTorch, with a focus on transferable
 pip install torchattack
 ```
 
-!!! note
+!!! danger "Under Construction"
 
     This page is currently under heavy construction.
 
-[All supported attacks :material-sword:](./attacks/index.md){ .md-button .md-button--primary }
+## Highlights
+
+- 🛡️ A curated collection of adversarial attacks implemented in PyTorch.
+- 🔍 Focuses on gradient-based transferable black-box attacks.
+- 📦 Easily load pretrained models from torchvision or timm using `AttackModel`.
+- 🔄 Simple interface to initialize attacks with `create_attack`.
+- 🔧 Extensively typed for better code quality and safety.
+- 📊 Tooling for fooling rate metrics and model evaluation in `eval`.
+- 🔁 Numerous attacks reimplemented for readability and efficiency (TGR, VDC, etc.).
+
+## Next Steps
+
+[Usage](./usage.md) | [Attacks](./attacks/index.md)
diff --git a/docs/populate_attack_apis.py b/docs/populate_attack_apis.py
@@ -0,0 +1,26 @@
+"""
+This script dynamically populates the markdown docs for each attack in the `attacks`
+directory. Each attack is documented in a separate markdown file with the attack's
+name as the filename. The content of each markdown file is dynamically generated
+from the docstrings of the attack classes in the `torchattack` module.
+
+Example of the generated docs:
+
+```markdown
+# MIFGSM
+
+::: torchattack.MIFGSM
+```
+"""
+
+import os
+
+import mkdocs_gen_files
+
+import torchattack as ta
+
+for attack_name in ta.SUPPORTED_ATTACKS:
+    filename = os.path.join('attacks', f'{attack_name.lower()}.md')
+    with mkdocs_gen_files.open(filename, 'w') as f:
+        f.write(f'# {attack_name}\n\n::: torchattack.{attack_name}\n')
+    mkdocs_gen_files.set_edit_path(filename, 'docs/populate_attack_apis.py')
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -0,0 +1,27 @@
+:root > * {
+  --md-primary-fg-color: #2066d6;
+  --md-accent-fg-color: #df332a;
+  --md-typeset-a-color: #2066d6;
+}
+
+[data-md-color-scheme="slate"] {
+  --md-default-bg-color: hsl(240, 12%, 14%);
+  --md-primary-fg-color: #3394e4 !important;
+  --md-accent-fg-color: #df332a !important;
+  --md-typeset-a-color: #3394e4 !important;
+}
+
+.md-header,
+.md-tabs {
+  color: inherit !important;
+  background-color: var(--md-default-bg-color);
+}
+[data-md-color-scheme="slate"] .md-header,
+[data-md-color-scheme="slate"] .md-tabs {
+  background-color: var(--md-default-bg-color);
+}
+@media screen and (min-width: 76.25em) {
+  [data-md-color-scheme="slate"] .md-tabs {
+    border-bottom: 0.05rem solid rgba(255, 255, 255, 0.07);
+  }
+}
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -3,6 +3,7 @@ site_url: https://spencerwooo.github.io/torchattack/
 repo_url: https://github.com/spencerwooo/torchattack
 repo_name: spencerwooo/torchattack
 edit_uri: edit/main/docs/
+copyright: Copyright &copy; 2023-Present Spencer Woo
 nav:
   - index.md
   - usage.md
@@ -20,13 +21,12 @@ theme:
     - media: "(prefers-color-scheme: light)"
       scheme: default
       primary: white
-      accent: red
       toggle:
         icon: material/weather-sunny
         name: Switch to dark mode
     - media: "(prefers-color-scheme: dark)"
       scheme: slate
-      accent: red
+      primary: black
       toggle:
         icon: material/weather-night
         name: Switch to system preference
@@ -49,6 +49,8 @@ theme:
     - navigation.indexes
     - content.code.annotate
     - content.tabs.link
+extra_css:
+  - stylesheets/extra.css
 markdown_extensions:
   - abbr
   - admonition
@@ -65,5 +67,15 @@ markdown_extensions:
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
 plugins:
   - search
-  - mkdocstrings
+  - gen-files:
+      scripts:
+        - docs/populate_attack_apis.py
   - awesome-pages
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            show_root_toc_entry: false
+            show_object_full_path: true
diff --git a/pyproject.toml b/pyproject.toml
@@ -34,6 +34,7 @@ dev = ["mypy>=1.13.0", "rich>=13.9.4", "timm>=1.0.12"]
 test = ["pytest-cov>=6.0.0", "pytest>=8.3.4"]
 docs = [
     "mkdocs-awesome-pages-plugin>=2.9.3",
+    "mkdocs-gen-files>=0.5.0",
     "mkdocs-material>=9.5.48",
     "mkdocstrings[python]>=0.27.0",
 ]