Add documentation framework with Mkdocs Material

.github/workflows/build-docs.yaml

@@ -0,0 +1,22 @@
+name: Build MkDocs
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v1
+
+      - name: Install version of Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11' 
+
+      - name: Install requirements
+        run: pip install -r requirements.txt
+
+      - name: Build docs
+        run: mkdocs build

.github/workflows/publishdocs.yaml

@@ -0,0 +1,21 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      actions: write
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v1
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/CNAME

@@ -0,0 +1 @@
+convert.lincbrain.org

docs/about.md

@@ -0,0 +1,11 @@
+# About this doc
+
+## Acknowledgements
+
+Thank you to the DANDI Archive project for setting up the documentation framework that is utilized here.  See the [DANDI Handbook](https://www.dandiarchive.org/handbook/) for more information.
+
+## License
+
+<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a>
+
+This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).

docs/contribute.md

@@ -0,0 +1,11 @@
+# Contribute to this documentation
+
+If you find an issue with this documentation please file an issue or submit a pull request on the [linc-convert repository](https://github.com/lincbrain/linc-convert).
+
+If you would like to contribute to the LINC documentation and render the documentation locally as you make edits, please follow the steps below:
+
+1. Fork the [linc-convert repository](https://github.com/lincbrain/linc-convert) and clone it to your computer.
+2. Set up a Python environment with the dependencies in the [requirements.txt file](https://github.com/lincbrain/linc-convert/blob/main/requirements.txt).
+3. Within the Python environment, run `mkdocs serve`.  This will build the website and start a local webserver (e.g. at http://127.0.0.1:8000) with your documentation.
+4. As you continue to edit the markdown files or configuration file, your documentation will be automatically re-built and rendered locally.
+5. Commit your changes and submit a pull request.

docs/index.md

@@ -0,0 +1,27 @@
+# Welcome to the LINC Convert Documentation
+
+<img
+src="./img/linc.logo.color+white.png"
+alt="linc_banner"
+style="width: 75%; height: auto; display: block; margin-left: auto; margin-right: auto;"/>
+
+The center for [Large-scale Imaging of Neural Circuits (LINC)](https://connects.mgh.harvard.edu/)
+ (PIs: Haber, Hillman, Yendiki) is funded by the
+ [NIH BRAIN Initiative CONNECTS program](https://www.ninds.nih.gov/news-events/highlights-announcements/nih-brain-initiative-launches-projects-develop-innovative-technologies-map-brain-incredible-detail).
+Its goal is to develop novel technologies for imaging brain connections down to 
+the microscopic scale, and deploy these technologies to image 
+cortico-subcortical projections that are relevant to deep brain stimulation for 
+motor and psychiatric disorders.
+
+## About this doc
+
+The `linc-convert` package converts dark-field microscopy, light-sheet microscopy, and polarization sensitive optical coherence tomography files to the OME-Zarr file format.
+
+## Quick Links
+
+- [LINC Homepage](https://connects.mgh.harvard.edu/)
+- [LINC data conversion code on GitHub](https://github.com/lincbrain/linc-convert)
+
+## Support
+
+For questions, bug reports, and feature requests, please file an issue on the [linc-convert](https://github.com/lincbrain/linc-convert) repository.

mkdocs.yml

@@ -0,0 +1,56 @@
+site_name: LINC Convert Documentation
+repo_name: "lincbrain/linc-convert"
+repo_url: "https://github.com/lincbrain/linc-convert"
+copyright: "CC-BY 4.0"
+use_directory_urls: true
+site_url: https://convert.lincbrain.org
+
+# Material theme
+theme:
+  name: "material"
+  language: "en"
+  favicon: img/linc.logo.color+white.notext+square.png
+  logo: img/linc.logo.color+black.alpha.notext.png
+  palette:
+    primary: "deep purple"
+    accent: "purple"
+  features:
+    - toc.integrate
+
+# Pages
+nav:
+  - Welcome: "index.md"
+  - API: api/
+  - Contribute documentation: "contribute.md"
+  - About this doc: "about.md"
+
+# List of extensions
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.critic
+  - pymdownx.magiclink
+  - toc:
+      permalink: True
+
+# List of plugins
+plugins:
+  - search
+  - open-in-new-tab
+
+# Customize theme
+extra:
+  generator: false
+  analytics:
+    provider: google
+    property: G-RJKYSKFW0P
+  social:
+    - icon: material/home
+      link: https://connects.mgh.harvard.edu/
+      name: Homepage
+    - icon: fontawesome/brands/slack
+      link: https://mit-lincbrain.slack.com/
+      name: Slack
+    - icon: fontawesome/brands/github
+      link: https://github.com/lincbrain
+      name: GitHub

requirements.txt

@@ -0,0 +1,3 @@
+mkdocs-material>=9.5.10
+pymdown-extensions
+mkdocs-open-in-new-tab