diff --git a/.github/workflows/build-docs.yaml b/.github/workflows/build-docs.yaml new file mode 100644 index 00000000..9b732eb4 --- /dev/null +++ b/.github/workflows/build-docs.yaml @@ -0,0 +1,23 @@ +name: Build MkDocs +on: + push: + pull_request: + workflow_dispatch: + +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 \ No newline at end of file diff --git a/.wordlist.txt b/.wordlist.txt index 39893ef1..5ef3517f 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,2 +1,13 @@ linc LINC +DANDI +PIs +Hillman +Yendiki +cortico +subcortical +OME +Zarr +txt +http +webserver \ No newline at end of file diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 00000000..f9a7f330 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +docs.lincbrain.org/linc-convert \ No newline at end of file diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 00000000..cb068a6e --- /dev/null +++ b/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 Docs](https://docs.dandiarchive.org) for more information. + +## License + +Creative Commons License + +This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/). diff --git a/docs/contribute.md b/docs/contribute.md new file mode 100644 index 00000000..b6736fbd --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/img/linc.logo.color+black.alpha.notext.png b/docs/img/linc.logo.color+black.alpha.notext.png new file mode 100644 index 00000000..f1379aab Binary files /dev/null and b/docs/img/linc.logo.color+black.alpha.notext.png differ diff --git a/docs/img/linc.logo.color+white.notext+square.png b/docs/img/linc.logo.color+white.notext+square.png new file mode 100644 index 00000000..19ac24cb Binary files /dev/null and b/docs/img/linc.logo.color+white.notext+square.png differ diff --git a/docs/img/linc.logo.color+white.png b/docs/img/linc.logo.color+white.png new file mode 100644 index 00000000..c19f3bef Binary files /dev/null and b/docs/img/linc.logo.color+white.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..2025e1ed --- /dev/null +++ b/docs/index.md @@ -0,0 +1,27 @@ +# Welcome to the LINC Convert Documentation + + + +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. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 00000000..9c79c703 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,76 @@ +site_name: LINC Convert +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://docs.lincbrain.org/linc-convert +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: + - scheme: default + toggle: + icon: material/weather-night + name: Dark mode + primary: "deep purple" + accent: "purple" + - scheme: slate + toggle: + icon: material/weather-sunny + name: Light mode + primary: "deep purple" + accent: "purple" + features: + - toc.integrate + +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: api.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 \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..cf4557bd --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/scripts/gen_ref_pages.py b/docs/scripts/gen_ref_pages.py new file mode 100644 index 00000000..d660d63a --- /dev/null +++ b/docs/scripts/gen_ref_pages.py @@ -0,0 +1,37 @@ +"""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" + +nav['Welcome']='index.md' +nav['Contribute']='contribute.md' +nav['About']='about.md' + +for path in sorted(src.rglob("*.py")): + doc_path = "api" / path.relative_to(src).with_suffix(".md") + full_doc_path = Path(root, "docs", doc_path) + module_path = path.relative_to(src).with_suffix("") + parts = tuple(module_path.parts) + + if parts[-1] == "__init__": + parts = parts[:-1] + elif parts[-1] == "__main__": + continue + + if parts: + parts_modified = ('API',) + parts + nav[parts_modified] = 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.md", "w") as nav_file: + nav_file.writelines(nav.build_literate_nav())