diff --git a/.docker/Dockerfile b/.docker/Dockerfile new file mode 100644 index 00000000..a700fa2b --- /dev/null +++ b/.docker/Dockerfile @@ -0,0 +1,6 @@ +FROM datajoint/miniconda3:4.10.3-py3.9-alpine +WORKDIR /main +COPY --chown=anaconda:anaconda ./.docker/pip_requirements.txt ${PIP_REQUIREMENTS} +RUN /entrypoint.sh echo "Dependencies installed" +COPY --chown=anaconda:anaconda ./mkdocs.yaml /main/mkdocs.yaml +COPY --chown=anaconda:anaconda ./src /main/src diff --git a/.docker/pip_requirements.txt b/.docker/pip_requirements.txt new file mode 100644 index 00000000..4420246b --- /dev/null +++ b/.docker/pip_requirements.txt @@ -0,0 +1,3 @@ +mkdocs-material +mkdocs-redirects +mdx_truly_sane_lists diff --git a/.github/workflows/development.yml b/.github/workflows/development.yml index 28b64c0f..3720fc79 100644 --- a/.github/workflows/development.yml +++ b/.github/workflows/development.yml @@ -4,12 +4,32 @@ on: branches: - main jobs: - deploy: + deploy-docs: runs-on: ubuntu-latest + env: + DOCKER_CLIENT_TIMEOUT: "120" + COMPOSE_HTTP_TIMEOUT: "120" steps: - uses: actions/checkout@v2 - - uses: actions/setup-python@v2 + - name: Compile docs static artifacts + run: | + MODE=BUILD HOST_UID=$(id -u) docker-compose up --exit-code-from docs --build + - name: Commit documentation changes + run: | + git clone https://github.com/${GITHUB_REPOSITORY}.git \ + --branch gh-pages --single-branch gh-pages + rm -R gh-pages/* + cp -r site/* gh-pages/ + cd gh-pages + git config --local user.email "action@github.com" + git config --local user.name "GitHub Action" + git add . --all + git commit -m "Update documentation" -a || true + # The above command will fail if no changes were present, so we ignore + # the return code. + - name: Push changes + uses: ad-m/github-push-action@master with: - python-version: 3.x - - run: pip install mkdocs-material - - run: mkdocs gh-deploy --force + branch: gh-pages + directory: gh-pages + github_token: ${{secrets.GITHUB_TOKEN}} diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..d97e1006 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +site \ No newline at end of file diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index 8f8550e1..00000000 --- a/.gitmodules +++ /dev/null @@ -1,8 +0,0 @@ -[submodule "docs/sub_docs/element-array-ephys"] - path = docs/sub_docs/element-array-ephys - url = https://github.com/A-Baji/element-array-ephys.git - branch = gh-pages -[submodule "docs/element-array-ephys"] - path = docs/element-array-ephys - url = https://github.com/A-Baji/element-array-ephys.git - branch = gh-pages diff --git a/README.md b/README.md index 3a642cf9..809d3311 100644 --- a/README.md +++ b/README.md @@ -1 +1,15 @@ -# documentation \ No newline at end of file +# DataJoint Documentation + +This is the home for all DataJoint's open-source and commercial documentation. + +## Test Locally + +To run locally, ensure you have `Docker` and `Docker Compose` installed. + +Then run the following: + +`MODE="LIVE" HOST_UID=$(id -u) docker compose up --build` + +Navigate to `http://localhost/` to preview the changes. + +This setup supports live-reloading so all that is needed is to save the markdown files and/or `mkdocs.yaml` file to trigger a reload. \ No newline at end of file diff --git a/docker-compose-mkdocs-serve.yaml b/docker-compose-mkdocs-serve.yaml deleted file mode 100644 index 730fae66..00000000 --- a/docker-compose-mkdocs-serve.yaml +++ /dev/null @@ -1,21 +0,0 @@ -# docker-compose -f ./docker-compose-mkdocs-serve.yaml up --build -version: "2.4" -services: - docs: - build: - context: . - dockerfile: docs.dockerfile - environment: - - THEME_DIR=material - volumes: - - .:/main - ports: - - 80:80 - command: - - bash - - -c - - | - pwd - mkdocs --version - mkdocs serve -a 0.0.0.0:80 - # tail -f /dev/null diff --git a/docker-compose-multirepo-build.yaml b/docker-compose-multirepo-build.yaml deleted file mode 100644 index 59da6d45..00000000 --- a/docker-compose-multirepo-build.yaml +++ /dev/null @@ -1,20 +0,0 @@ -# HOST_UID="$(id -u)" HOST_GID="$(id -g)" docker-compose -f ./docker-compose-multirepo-build.yaml up --build -version: "2.4" -services: - docs: - build: - context: . - dockerfile: docs.build.dockerfile - volumes: - - .:/main - user: '${HOST_UID}:${HOST_GID}' - command: - - bash - - -c - - | - pwd - git init - git submodule init - git submodule update - git submodule foreach git pull origin gh-pages - # tail -f /dev/null diff --git a/docker-compose.yaml b/docker-compose.yaml new file mode 100644 index 00000000..d63dc3a0 --- /dev/null +++ b/docker-compose.yaml @@ -0,0 +1,30 @@ +# MODE="LIVE|BUILD" HOST_UID=$(id -u) docker compose up --build +# +# Navigate to http://localhost/ +version: "2.4" +services: + docs: + build: + dockerfile: .docker/Dockerfile + context: . + image: datajoint/documentation + environment: + - MODE + volumes: + - .:/main + user: ${HOST_UID}:anaconda + ports: + - 80:80 + command: + - sh + - -c + - | + set -e + if echo "$${MODE}" | grep -i live &>/dev/null; then + mkdocs serve --config-file ./mkdocs.yaml -a 0.0.0.0:80 + elif echo "$${MODE}" | grep -i build &>/dev/null; then + mkdocs build --config-file ./mkdocs.yaml + else + echo "Unexpected mode..." + exit 1 + fi diff --git a/docs.build.dockerfile b/docs.build.dockerfile deleted file mode 100644 index 0ff27cfb..00000000 --- a/docs.build.dockerfile +++ /dev/null @@ -1,5 +0,0 @@ -FROM python:latest - -WORKDIR /main -COPY . /main -RUN pip install mkdocs mkdocs-material \ No newline at end of file diff --git a/docs.dockerfile b/docs.dockerfile deleted file mode 100644 index 63fea08e..00000000 --- a/docs.dockerfile +++ /dev/null @@ -1,5 +0,0 @@ -FROM python:slim - -WORKDIR /main -COPY . /main -RUN pip install mkdocs mkdocs-material \ No newline at end of file diff --git a/docs/assets/elements-logo.png b/docs/assets/elements-logo.png deleted file mode 100644 index 19b392a9..00000000 Binary files a/docs/assets/elements-logo.png and /dev/null differ diff --git a/docs/element-array-ephys b/docs/element-array-ephys deleted file mode 160000 index 97b46206..00000000 --- a/docs/element-array-ephys +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 97b4620698de3c012afdb39b39ee6c85ffeeacc4 diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index d33d2ef7..00000000 --- a/docs/index.md +++ /dev/null @@ -1,56 +0,0 @@ -# Welcome to Docs Hub - -For full documentation visit [mkdocs.org](https://www.mkdocs.org). - -## Projects - - - - -
- - - -## Commands - -* `mkdocs new [dir-name]` - Create a new project. -* `mkdocs serve` - Start the live-reloading docs server. -* `mkdocs build` - Build the documentation site. -* `mkdocs -h` - Print help message and exit. - -## Project layout - - mkdocs.yml # The configuration file. - docs/ - index.md # The documentation homepage. - ... # Other markdown pages, images and other files. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css deleted file mode 100644 index 9a8e3ecf..00000000 --- a/docs/stylesheets/extra.css +++ /dev/null @@ -1,36 +0,0 @@ -[data-md-color-scheme="datajoint"] { - - --dj-yellow: #fcb954; - - --md-primary-fg-color: var(--dj-yellow); - --md-primary-bg-color: #000000; - --md-primary-fg-color--dark: var(--dj-yellow); - - --md-accent-fg-color: var(--dj-yellow); - - --md-code-bg-color: #e4f3f6; - - --md-footer-fg-color: var(--dj-yellow); -} - -[data-md-color-scheme="slate"] { - - --dj-yellow: #fcb954; - - --md-typeset-color: #e4f3f6; - --md-typeset-a-color: #17b2ff; - - --md-default-fg-color: #e4f3f6; - --md-default-fg-color--light: var(--dj-yellow); - - --md-primary-fg-color: var(--dj-yellow); - --md-primary-bg-color: #000000; - --md-primary-fg-color--dark: var(--dj-yellow); - - --md-accent-fg-color: var(--dj-yellow); - - --md-code-fg-color: #76c9e9; - --md-code-hl-comment-color: #ffd28d; - - --md-footer-fg-color: var(--dj-yellow); -} \ No newline at end of file diff --git a/docs/stylesheets/styles.css b/docs/stylesheets/styles.css deleted file mode 100644 index 04f0c1a8..00000000 --- a/docs/stylesheets/styles.css +++ /dev/null @@ -1,44 +0,0 @@ -section { - max-width: 44.5rem; - padding: 0; - color: #3c4043; - line-height: 1.25rem; -} - -section ul { - margin: 0; - outline: 0; - padding: 0; - display: inline-block; - max-width: 44.5rem; -} - -section li { - min-height: 3.125rem; - vertical-align: top; - display: inline-block; -} - -section li > a { - max-height: 7rem; - padding: 0.5rem; - margin: 0.5rem; - border: .0625rem solid #dadce0; - border-radius: .5rem; - display: block; -} - -section li img { - width: 4rem; - height: auto; - display: block; - margin-left: auto; - margin-right: auto; -} - -section li span { - height: auto; - display: block; - margin: .5rem 0; - text-align: center; -} \ No newline at end of file diff --git a/docs/sub_docs.html b/docs/sub_docs.html deleted file mode 100644 index df18da4b..00000000 --- a/docs/sub_docs.html +++ /dev/null @@ -1,16 +0,0 @@ - - - - - -
- -
- \ No newline at end of file diff --git a/mkdocs.yaml b/mkdocs.yaml new file mode 100644 index 00000000..f3ca037e --- /dev/null +++ b/mkdocs.yaml @@ -0,0 +1,75 @@ +# ---------------------- PROJECT SPECIFIC --------------------------- + +site_name: DataJoint Documentation +repo_url: https://github.com/datajoint-company/documentation +repo_name: datajoint-company/documentation +nav: + - Welcome: welcome.md + - Concepts: + - Datatypes: concepts/datatypes.md + - Core: core.md + - Elements: elements.md + - Glossary: glossary.md + - Community: + - Contribution: community/contribution.md + +# ---------------------------- STANDARD ----------------------------- + +docs_dir: ./src +edit_uri: ./edit/main/src +theme: + name: material + custom_dir: src/.overrides + logo: assets/images/project-logo-black.png + favicon: assets/images/project-logo-color.png + features: + - toc.integrate + palette: + - media: "(prefers-color-scheme: light)" + scheme: datajoint + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode +plugins: + - search + - redirects: + redirect_maps: + "index.md": "welcome.md" +markdown_extensions: + - attr_list + - toc: + permalink: true + - pymdownx.emoji: + options: + custom_icons: + - .overrides/.icons + - mdx_truly_sane_lists + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format +extra: + generator: false # Disable watermark + social: + - icon: datajoint/company-logo + link: https://www.datajoint.com/ + - icon: fontawesome/brands/slack + link: https://datajoint.slack.com + - icon: fontawesome/brands/linkedin + link: https://www.linkedin.com/company/datajoint + - icon: fontawesome/brands/twitter + link: https://twitter.com/DataJointIO + - icon: fontawesome/brands/github + link: https://github.com/datajoint + - icon: fontawesome/brands/stack-overflow + link: https://stackoverflow.com/questions/tagged/datajoint + - icon: fontawesome/brands/youtube + link: https://www.youtube.com/channel/UCdeCuFOTCXlVMRzh6Wk-lGg +extra_css: + - assets/stylesheets/extra.css \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index 982c3bc8..00000000 --- a/mkdocs.yml +++ /dev/null @@ -1,19 +0,0 @@ -site_name: DataJoint Core Docs -repo_url: https://github.com/datajoint/documentation -repo_name: datajoint/documentation -theme: - name: material - palette: - - media: "(prefers-color-scheme: light)" - scheme: datajoint - toggle: - icon: material/brightness-7 - name: Switch to dark mode - - media: "(prefers-color-scheme: dark)" - scheme: slate - toggle: - icon: material/brightness-4 - name: Switch to light mode - -extra_css: - - stylesheets/extra.css diff --git a/src/.overrides/.icons/datajoint/company-logo.svg b/src/.overrides/.icons/datajoint/company-logo.svg new file mode 100644 index 00000000..b99eecb2 --- /dev/null +++ b/src/.overrides/.icons/datajoint/company-logo.svg @@ -0,0 +1,20 @@ + + www.datajoint.com + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/.overrides/assets/images/project-logo-black.png b/src/.overrides/assets/images/project-logo-black.png new file mode 100644 index 00000000..c8536889 Binary files /dev/null and b/src/.overrides/assets/images/project-logo-black.png differ diff --git a/src/.overrides/assets/images/project-logo-color.png b/src/.overrides/assets/images/project-logo-color.png new file mode 100644 index 00000000..828d87ca Binary files /dev/null and b/src/.overrides/assets/images/project-logo-color.png differ diff --git a/src/.overrides/assets/stylesheets/extra.css b/src/.overrides/assets/stylesheets/extra.css new file mode 100644 index 00000000..7d638c03 --- /dev/null +++ b/src/.overrides/assets/stylesheets/extra.css @@ -0,0 +1,36 @@ +[data-md-color-scheme="datajoint"] { + + --dj-yellow: #fcb954; + + --md-primary-fg-color: var(--dj-yellow); + --md-primary-bg-color: #000000; + --md-primary-fg-color--dark: var(--dj-yellow); + + --md-accent-fg-color: var(--dj-yellow); + + --md-code-bg-color: #e4f3f6; + + --md-footer-fg-color: var(--dj-yellow); +} + +[data-md-color-scheme="slate"] { + + --dj-yellow: #fcb954; + + --md-typeset-color: #e4f3f6; + --md-typeset-a-color: #17b2ff; + + --md-default-fg-color: #e4f3f6; + --md-default-fg-color--light: var(--dj-yellow); + + --md-primary-fg-color: var(--dj-yellow); + --md-primary-bg-color: #000000; + --md-primary-fg-color--dark: var(--dj-yellow); + + --md-accent-fg-color: var(--dj-yellow); + + --md-code-fg-color: #76c9e9; + --md-code-hl-comment-color: #ffd28d; + + --md-footer-fg-color: var(--dj-yellow); +} \ No newline at end of file diff --git a/src/community/contribution.md b/src/community/contribution.md new file mode 100644 index 00000000..e42eebf1 --- /dev/null +++ b/src/community/contribution.md @@ -0,0 +1,7 @@ +# Contribution Guidelines + +Thank you for your interest in contributing! 🤝 + +To help keep everyone in alignment and coordinated in the community effort, we’ve created this document. It serves as the contribution guideline that outlines how open-source software development is to be conducted. Any software development that makes reference to this document can be assumed to adopt the policies outlined below. We’ve structured the guideline in a FAQ (frequently asked questions) format to make it easier to digest. Feel free to review the questions below to determine any specific policy. + +The principal maintainer of DataJoint and associated tools is the DataJoin company. The pronouns “we” and “us” in this guideline refer to the principal maintainers. We invite reviews and contributions of the open-source software. We compiled these guidelines to make this work clear and efficient. \ No newline at end of file diff --git a/src/concepts/datatypes.md b/src/concepts/datatypes.md new file mode 100644 index 00000000..b02dc6bb --- /dev/null +++ b/src/concepts/datatypes.md @@ -0,0 +1,17 @@ +# Datatypes + +Throughout the DataJoint ecosystem, there are several datatypes that are used to define tables with cross-platform support i.e. Python, MATLAB. It is important to understand these types as they can have implications in the queries you form and the capacity of their storage. + +## Standard Types + +These types are largely wrappers around existing types in MySQL since this is the backend to the DataJoint Engine. + +| Datatype | Description | Size | Example | +| --- | --- | ---| --- | +| int | integer | 4 bytes | `8` | + +## Unique Types + +| Datatype | Description | Size | Example | +| --- | --- | ---| --- | +| uuid | a unique GUID value | 16 bytes | `6ed5ed09-e69c-466f-8d06-a5afbf273e61` | \ No newline at end of file diff --git a/src/core.md b/src/core.md new file mode 100644 index 00000000..5cec6262 --- /dev/null +++ b/src/core.md @@ -0,0 +1,42 @@ +# Core + +## Relational Database + +- MySQL usage +- Optimal configuration +- Maintenance +- Permission management and access control + + +## Programming Interfaces + +Below are the projects that make up the family of core open-source projects: + +- **[Python API](https://datajoint.com/docs/core/datajoint-python/)**: Relational framework that allows for intuitive queries and reproducible computation. +- **[MATLAB API](https://datajoint.com/docs/core/datajoint-matlab/)**: Relational framework that allows for intuitive queries and reproducible computation. +- **[Pharus](https://datajoint.com/docs/core/pharus/)**: REST interface for communicating with data pipelines. + +## Web Interfaces + +- **[LabBook](https://datajoint.com/docs/core/datajoint-labbook/)**: Data entry and data model browsing web GUI. +- **[SciViz](https://datajoint.com/docs/core/sci-viz/)**: Visualization framework for making low-code web apps. + +## Container Images + +``` mermaid +graph + datajoint/mysql; + datajoint/miniconda3 --> datajoint/djbase; + datajoint/djbase --> datajoint/djtest; + datajoint/djbase --> datajoint/datajoint; + datajoint/djbase --> datajoint/djlab; + datajoint/djlab --> datajoint/djlabhub; +``` + +- **[datajoint/mysql](https://datajoint.com/docs/core/mysql-docker/)**: Optimized MySQL image for use with DataJoint Engine. +- **[datajoint/miniconda3](https://datajoint.com/docs/core/miniconda3-docker/)**: Minimal Python image with `conda`. +- **[datajoint/djbase](https://datajoint.com/docs/core/djbase-docker/)**: DataJoint engine dependencies only. +- **[datajoint/djtest](https://datajoint.com/docs/core/djtest-docker/)**: Includes testing tools like `pytest`. +- **[datajoint/datajoint](https://datajoint.com/docs/core/datajoint-python/)**: Official DataJoint engine image. +- **[datajoint/djlab](https://datajoint.com/docs/core/djlab-docker/)**: Includes local Jupyter Lab environment. +- **[datajoint/djlabhub](https://datajoint.com/docs/core/djlabhub-docker/)**: Includes necessary dependencies for launching with Jupyter Hub. \ No newline at end of file diff --git a/src/elements.md b/src/elements.md new file mode 100644 index 00000000..fbbb4304 --- /dev/null +++ b/src/elements.md @@ -0,0 +1,7 @@ +# Elements + +Below are the projects that make up the family of open-source DataJoint Elements: + +## Neuroscience + +- **[Ephys](https://datajoint.com/docs/elements/element-array-ephys/)**: Neuropixels analysis with Kilosort \ No newline at end of file diff --git a/src/glossary.md b/src/glossary.md new file mode 100644 index 00000000..02f523d3 --- /dev/null +++ b/src/glossary.md @@ -0,0 +1,9 @@ +# Glossary + +There are many terms that are reused throughout the documentation that we feel it imporant to define together. We've taken careful consideration to be consistent so below you will find how we've understood and use these terms. + +| Term | Definition | +| --- | --- | +| DAG | directed acyclic graph | +| task | an independent unit of processing | +| workflow | programs that are guaranteed to eventually reach a terminal state represented as DAGs of tasks | \ No newline at end of file diff --git a/src/welcome.md b/src/welcome.md new file mode 100644 index 00000000..ebcdd1ea --- /dev/null +++ b/src/welcome.md @@ -0,0 +1,9 @@ +# Howdy :wave: + +Welcome to the home for DataJoint documentation. We'll guide you to help you find what you are looking for quickly. + +The ecosystem is divided into 2 distinct areas: + +**Core**: Fully open-source projects built and designed specifically for the DataJoint engine. + +**Elements**: Fully open-source, domain-specific projects built with DataJoint Core. Primarily with a focus on neuroscience. \ No newline at end of file