slaclab · zdomke · Sep 2, 2025 · Aug 20, 2025 · Aug 20, 2025 · Aug 21, 2025
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -9,30 +9,29 @@ on:
 
 jobs:
   deploy:
-    if: ${{ github.repository == 'slaclab/trace' }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest]
-        python-version: [3.12]
+    runs-on: ubuntu-latest
+
     steps:
-      - uses: actions/checkout@v3
-      - uses: conda-incubator/setup-miniconda@v2
+      - uses: actions/checkout@v4
         with:
-          miniforge-version: latest
-          use-mamba: true
-          python-version: ${{ matrix.python-version }}
-          channels: conda-forge
-          activate-environment: trace-dev
-          environment-file: environment.yml
+          fetch-depth: 0
+          sparse-checkout: |
+            docs
 
-      - name: Build Docs
-        shell: bash -l {0}
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
         run: |
-          mkdocs build
+          pip install -r docs-requirements.txt
+
+      - name: Build Docs
+        run: mkdocs build
 
       - name: Deploy to gh-pages
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site/
+          publish_dir: ./site
diff --git a/.gitignore b/.gitignore
@@ -142,4 +142,5 @@ debug_archive_viewer.bash
 debug_trace.bash
 
 # Image files
-*.png
+*.png
+!docs/**/*.png
diff --git a/docs-requirements.txt b/docs-requirements.txt
@@ -0,0 +1,6 @@
+mkdocs
+mkdocs-material
+mkdocstrings
+mkdocstrings-python
+mkdocs-git-revision-date-localized-plugin
+mkdocs-git-committers-plugin-2
diff --git a/docs/api_reference/axis_table.md b/docs/api_reference/axis_table.md
diff --git a/docs/api_reference/plot_config.md b/docs/api_reference/plot_config.md
diff --git a/docs/api_reference/trace.md b/docs/api_reference/trace.md
diff --git a/docs/api_reference/traces_table.md b/docs/api_reference/traces_table.md
diff --git a/docs/arguments.md b/docs/arguments.md
@@ -0,0 +1,57 @@
+# Input Arguments & Macros
+
+Trace supports several optional startup arguments and macros that allow users to customize its behavior at launch. These arguments let you specify input files, define process variables (PVs) to display, apply macro replacements, and access help or version information.
+
+Below, you'll find a detailed overview of each available argument and example usage to help you configure Trace to fit your workflow.
+
+
+## Config File
+
+`-i INPUT_FILE` or `--input_file INPUT_FILE`
+
+This argument allows users to [import] Trace config files, providing a way to recover a previous state of Trace. To make use of it, users should provide a filepath for the config file they want to use. The path can be either relative or absolute.
+
+  [import]: io.md
+
+``` bash
+pydm trace/main.py -i trace/examples/FormulaExample.trc
+```
+
+
+## Startup PVs
+
+`-p PV1 PV2 ...` or `--pvs PV1 PV2 ...`
+
+Users are able to provide a list of PVs to show traces for on startup. Each PV passed here will be represented by a curve on the plot.
+
+``` bash
+pydm trace/main.py -p FOO:BAR:CHANNEL SOME:OTHER:CHANNEL
+```
+
+
+## Macros
+
+`-m MACRO` or `--macro MACRO`
+
+Use PyDM's [macro substitution] system as another way of adding PVs or startup files to Trace. Adding PVs via macros is equivalent to adding them as an argument. This setup allows users to add traces from other PyDM widgets, such as the [PyDMRelatedDisplayButton].
+
+  [macro substitution]: https://slaclab.github.io/pydm/tutorials/intro/macros.html
+  [PyDMRelatedDisplayButton]: https://slaclab.github.io/pydm/widgets/related_display_button.html
+
+``` bash
+pydm trace/main.py -m '{"PVS": ["FOO:BAR:CHANNEL", "SOME:OTHER:CHANNEL"]}'
+pydm trace/main.py -m "INPUT_FILE = trace/examples/FormulaExample.trc"
+```
+
+
+## Help Message
+
+`-h` or `--help`
+
+Shows Trace's help message, which outlines the available arguments for users.
+
+## Version Number
+
+`-v` or `--version`
+
+Show Trace's current version/release number.
diff --git a/docs/how_to/file_conversion.md b/docs/how_to/file_conversion.md
diff --git a/docs/how_to/overview.md b/docs/how_to/overview.md
diff --git a/docs/how_to/traces.md b/docs/how_to/traces.md
diff --git a/docs/images/Trace_Screenshot.png b/docs/images/Trace_Screenshot.png
diff --git a/docs/images/axis_settings.png b/docs/images/axis_settings.png
diff --git a/docs/images/config_section.png b/docs/images/config_section.png
diff --git a/docs/images/footer.png b/docs/images/footer.png
diff --git a/docs/images/formula_maker.png b/docs/images/formula_maker.png
diff --git a/docs/images/line_style.png b/docs/images/line_style.png
diff --git a/docs/images/line_type.png b/docs/images/line_type.png
diff --git a/docs/images/plot_section.png b/docs/images/plot_section.png
diff --git a/docs/images/search_tool.png b/docs/images/search_tool.png
diff --git a/docs/images/sections.png b/docs/images/sections.png
diff --git a/docs/images/sqwave-blwh.svg b/docs/images/sqwave-blwh.svg
diff --git a/docs/images/trace_settings.png b/docs/images/trace_settings.png
diff --git a/docs/images/traces.png b/docs/images/traces.png
diff --git a/docs/images/y_axes.png b/docs/images/y_axes.png
diff --git a/docs/index.md b/docs/index.md
@@ -1,5 +1,25 @@
+---
+hide:
+  - footer
+  - navigation
+  - toc
+---
+
 # Trace
 
-[Trace](https://github.com/slaclab/trace) is a PyDM-based application developed at SLAC National Accelerator Laboratory. Trace has been built to replace the antiquated StripTool and Java Archive Viewer applications used to plot EPICS data. Trace is a flexible, modern application for plotting live data (Channel Access or PV Access), and historical data from the EPICS Archive Appliance. With built in conveniences like an archived PV search, and designed to be easily launched from PyDM widgets, files, or the command line, Trace will provide an improved user experience for accelerator staff. Trace is an open-source project.   
+[Trace] is a PyDM-based application developed at SLAC National Accelerator Laboratory.
+
+  [Trace]: https://github.com/slaclab/trace/
+
+The motivation behind trace is as a replacement for the StripTool and Java Archive Viewer applications used to plot EPICS data. It is a flexible, modern application for plotting live data (Channel Access or PV Access), and historical data from the EPICS Archive Appliance.
+
+With built in conveniences like an archived PV search, and designed to be easily launched from PyDM widgets, files, or the command line, Trace will provide an improved user experience for accelerator staff.
+
+Trace is open-source and in active development, so don't hesitate to [request features] or [report bugs].
+
+  [request features]: https://github.com/slaclab/trace/issues/new?labels=enhancement&projects=&template=feature-request.yml&title=%5BFEATURE%5D+-+
+  [report bugs]: https://github.com/slaclab/trace/issues/new?labels=bug&projects=&template=bug-report.yml&title=%5BBUG%5D+-+
 
-![Image of Trace](images/Index_Image.png)
+<figure markdown="span">
+  ![Trace Screenshot](images/trace_screenshot.png)
+</figure>