Add documentation framework

.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 docs/requirements.txt
+
+      - name: Build docs
+        run: mkdocs build -f docs/mkdocs.yml

.github/workflows/publishdocs.yaml

@@ -0,0 +1,24 @@
+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 }}
+          CUSTOM_DOMAIN: convert.lincbrain.org
+          CONFIG_FILE: docs/mkdocs.yml
+          REQUIREMENTS: docs/requirements.txt

.wordlist.txt

@@ -1,2 +1,13 @@
 linc
 LINC
+DANDI
+PIs
+Hillman
+Yendiki
+cortico
+subcortical
+OME
+Zarr
+txt
+http
+webserver

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](https://github.com/lincbrain/linc-convert) repository.
+
+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](https://github.com/lincbrain/linc-convert) repository and clone it to your computer.
+2. Set up a Python environment with the dependencies in the [requirements.txt](https://github.com/lincbrain/linc-convert/blob/main/requirements.txt) file.
+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.

docs/mkdocs.yml

@@ -0,0 +1,75 @@
+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
+docs_dir: "."
+site_dir: "../site"
+edit_uri: "blob/main/docs/"
+
+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
+
+watch:
+  - ../linc_convert
+
+nav:
+  - Welcome: "index.md"
+  - API: api/
+  - Contribute documentation: "contribute.md"
+  - About this doc: "about.md"
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.critic
+  - pymdownx.magiclink
+  - toc:
+      permalink: True
+
+plugins:
+  - search
+  - open-in-new-tab
+  - section-index
+  - same-dir
+  - gen-files:
+      scripts:
+      - scripts/gen_ref_pages.py 
+  - literate-nav:
+      nav_file: navigation.md
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [..]
+          options:
+            docstring_style: numpy
+            show_source: false
+            merge_init_into_class: true
+            separate_signature: true
+            members_order: source
+            show_root_heading: true
+
+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

docs/requirements.txt

@@ -0,0 +1,8 @@
+mkdocs-material>=9.5.10
+pymdown-extensions
+mkdocs-open-in-new-tab
+mkdocstrings[python]>=0.18
+mkdocs-gen-files
+mkdocs-literate-nav
+mkdocs-section-index
+mkdocs-same-dir

docs/scripts/gen_ref_pages.py

@@ -0,0 +1,33 @@
+"""Create a navigation file and markdown files for API docs."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent.parent
+src = root / "linc_convert"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path(root, "docs/api", doc_path)
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+    elif parts[-1] == "__main__":
+        continue
+
+    if parts:
+        nav[parts] = Path(doc_path).as_posix()
+        with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+            ident = ".".join(parts)
+            fd.write(f"::: linc_convert.{ident}")
+
+        mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open(root / "docs/api/navigation.md", "w") as nav_file: 
+    nav_file.writelines(nav.build_literate_nav())
+