hello world

Author: MMathisLab

README.md

@@ -0,0 +1,95 @@
+
+# Code Guidelines
+
+The hub for discussions and best practices on code management! The goal is someone can fork/clone this repo and start a new project easily. This was written by Mackenzie Mathis, and I thank my lab and the open-source community for many lessons learned.
+
+## Overview
+
+This repository is a work-in-progress template for structuring coding projects with clean, reproducible, and collaborative workflows. It includes tools and practices that streamline development, documentation, testing, and deployment.
+
+### Core Components
+
+1. **Code Organization**
+
+   * Make a clear folder structure for modules, tests, and configs; try to keep this across project/s
+   * Naming conventions and modular design principles, [here are useful standards](https://dmeg.cessda.eu/Data-Management-Expert-Guide/2.-Organise-Document/File-naming-and-folder-structure) to consider.
+
+#### Recommended Directory Structure
+
+```bash
+project_name/
+├── README.md
+├── LICENSE
+├── pyproject.toml
+├── setup.cfg
+├── .gitignore
+├── .pre-commit-config.yaml
+├── _toc.yml
+├── docker/
+│   └── Dockerfile
+├── examples/
+│   └── basic_usage.ipynb
+├── placeholder (project_name)/   # Main package code
+│   ├── __init__.py
+│   ├── module_example.py
+    ├── version.py
+│   └── utils/
+│       └── helpers.py
+├── tests/
+│   ├── __init__.py
+│   ├── test_module1.py
+│   └── conftest.py
+├── docs/             # JupyterBook documentation
+│   ├── _config.yml
+│   └── index.md
+└── .github/
+    └── workflows/
+        └── codespell.yml
+        └── publish-book.yml
+```
+
+2. **Documentation**
+
+   * [JupyterBook](https://jupyterbook.org/en/stable/intro.html) setup for comprehensive, interactive project documentation!
+   * Here are [guidelines for writing readable and maintainable docstrings](https://www.datacamp.com/tutorial/docstrings-python) - this is as important as documentation!
+
+3. **Code Formatting & Linting**
+
+   * Formatted code makes your life and those who use/review your code easier. Standardized formatting with tools like `black` and `isort` (see the provided `.pre-commit-config.yaml`).
+   * [Pre-commit hooks](https://pre-commit.com/) to automate checks before pushing code! Follow their quick Guide to do this, but in short:
+   (1) install it in your dev env
+   ```python
+      pip install pre-commit
+   ```
+   (2) install the git hooks:
+   ```python
+   pre-commit install
+   ```
+   (3) Just run it on your code BEFORE you git push:
+   ```python
+   pre-commit run --all-files
+   ```
+4. **Continuous Integration**
+
+   * Use GitHub Actions for automated testing and code quality checks
+   * This template repo gies you built-in `codespell`, `publish-book` and `pre-commit` validations (go to actions in your repo to follow the guidelines to set up/also chatGPT can help ;)
+
+5. **Containerization**
+
+   * Docker setup for consistent development and deployment environments - this is not just an after thought, use Docker to develop and share your code!
+   * Examples of `Dockerfile` and `docker-compose.yml` configurations (coming)
+   * You are welcome/encouraged to use our containers: https://hub.docker.com/u/mmathislab
+
+6. **Data Workflow Integration**
+
+   * [DataJoint](https://www.datajoint.com/) examples for managing and querying scientific data pipelines - these are a must; use minimally for data + meta data storage, and use it to automate things you do daily (preprocessing, running DeepLabCut, etc!)
+   * [Templates for common workflows and schema management are here!](https://docs.datajoint.com/elements/)
+
+---
+
+Contributions welcome as we refine this template!
+
+
+## Acknowledgement
+
+Some items in this repo are adapted from [DeepLabCut](https://github.com/DeepLabCut/DeepLabCut), [CEBRA](https://cebra.ai/), and the [Mathis Lab of Adaptive Intelligence](https://github.com/orgs/AdaptiveMotorControlLab). It is under an Apache 2.0 License.

__init__.py

@@ -0,0 +1,28 @@
+title: DocTemplate
+author: MWM
+logo: docs/logo.png
+only_build_toc_files: true
+
+sphinx:
+  config:
+    autodoc_mock_imports: list #["wx"]
+  extra_extensions:
+    - numpydoc
+
+execute:
+  execute_notebooks: "off"
+
+html:
+  extra_navbar: ""
+  use_issues_button: true
+  use_repository_button: true
+  extra_footer: |
+    <div>Powered by <a href="https://jupyterbook.org/">Jupyter Book</a>.</div>
+
+repository:
+  url: https://github.com/SCENE-Collaboration/Code_and_Documentation_Guidelines #change me
+  path_to_book: docs
+  branch: main
+
+launch_buttons:
+  colab_url: "https://colab.research.google.com/github/SCENE-Collaboration/Code_and_Documentation_Guidelines/examples/yourdemo.ipynb"

_config.yml

@@ -0,0 +1,7 @@
+format: jb-book
+root: README
+parts:
+- caption: Main Documentation
+  chapters:
+  - file: docs/HowTo_JupyterBook
+  - file: docs/Learning_reseources

_toc.yml

@@ -0,0 +1,36 @@
+# What is Jupyterbook?
+
+https://jupyterbook.org/en/stable/intro.html
+
+
+## Quick start
+- have your repo cloned and run this to generate a starting template:
+```python
+jupyter-book create --cookiecutter YourClonedRepo/
+```
+
+### Build from the template provided
+
+(1) Use and adapt the two template files (_toc.yml, _config.yml) to your main code base, and be sure to keep the `docs` structure, i.e.,
+```
+/docs
+├── /images
+│   └── logo.png         # add logo here
+├── intro.md             # main welcome page
+
+```
+(2) write in markdown (or myst) your docs, as usual:
+- for an example: https://github.com/DeepLabCut/DeepLabCut/blob/mmain/docs/intro.md
+
+(3) to build your docs & hosting see here: https://jupyterbook.org/en/stable/publish/gh-pages.html
+
+TL;DR in the main repo run:
+```python
+❯ jupyter-book build .
+```
+and then follow terminal prompt (check errors, etc)- viola!
+
+
+To then deploy the book live, see: https://jupyterbook.org/en/stable/publish/gh-pages.html#automatically-host-your-book-with-github-actions
+
+In short, you will set up a git action to deploy to a new branch (that you never merge) called `gh-pages`

docs/HowTo_JupyterBook.md

@@ -0,0 +1,36 @@
+# Learning Resources
+
+Here is a growing list of resources that I've (Mackenzie M.) found useful for learning about various topics.
+
+## Python
+
+- [Python.org](https://www.python.org/)
+- [Real Python](https://realpython.com/)
+- [Automate the Boring Stuff with Python](https://automatetheboringstuff.com/)
+
+## SQL
+
+- [mySQL](https://dev.mysql.com/doc/)
+- [SQL Zoo](https://sqlzoo.net/)
+
+## Data Science
+
+- [DataJoint](https://datajoint.io/)
+
+## Machine Learning
+
+- [Scikit-learn](https://scikit-learn.org/)
+- [TensorFlow](https://www.tensorflow.org/)
+- [PyTorch](https://pytorch.org/)
+
+## Jupyter
+- Dissection of Jupyter ecosystem by Chris Holdgraf https://www.youtube.com/watch?v=t0MjcXZf7SM (40 min⏰)
+- The Guide📙: How to make a JB basics/tips/features by Chris Holdgraf https://www.youtube.com/watch?v=lZ2FHTkyaMU (30 min⏰) - most updated video
+-Similar to 2 from Jupyter meets earth https://www.youtube.com/watch?v=seKOq-VMJgY (as they cover the same topic there are many duplications) updated the past 9 months (22 min⏰)
+- Honorary mention with features and comments from JupyterCon https://www.youtube.com/watch?v=tUDHysfzAxs (30 min⏰)
+- In the documentation it is important to start from the anatomy of jb https://jupyterbook.org/en/stable/start/create.html#anatomy-of-a-book and the command line interface reference https://jupyterbook.org/en/stable/reference/cli.html
+
+## Git
+
+- Crash course tutorial: https://www.youtube.com/watch?v=RGOj5yH7evk&t=2543s (70 min⏰)
+- Interactive with all the basics https://www.youtube.com/watch?v=8JJ101D3knE&t=3131s (70 min⏰)

docs/Learning_resources.md

@@ -0,0 +1,41 @@
+# Introduction
+
+This is the intro to the JupyterBook!
+
+This is just a placeholder for you to document your package.
+
+
+## Developer Guide
+
+### 0. Edit your `config` and `toc` to your specs.
+
+### 1. Set Organization-level Permissions (already done for SCENE)
+Go to:
+`Org Settings` → `Actions` → `General` → `Select the repo` → Check:
+
+"Allow GitHub Actions to access the GITHUB_TOKEN with write permissions" must be enabled.
+
+"Workflow permissions" must allow read and write by default, or per repo.
+
+
+
+### 2. Deploy the Docs
+
+First, this is done via the GitHub actions `publish-book.yml`.
+
+To get a public `github.io` link, you must enable GitHub Pages.
+Note, this only works for public repos, or if private, from paid org.
+
+### Steps:
+
+1. Go to your repo → **Settings** → **Pages**
+2. Under **"Source"**, select:
+
+   * **Branch**: e.g., `main`
+   * **Folder**: `/_build/html`
+3. Click **"Save"**
+
+GitHub will deploy your book and show a link like:
+`https://<username>.github.io/<repo>/`
+
+Deployment may take a minute. Refresh the page to see the live link!

docs/intro

@@ -0,0 +1,4 @@
+#
+
+__version__ = "0.0.0rc1"
+VERSION = __version__

placeholder/__init__.py

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.yapf]
+based_on_style = "google"
+indent_width = 4
+
+[tool.isort]
+force_single_line = true
+force_sort_within_sections = false
+lexicographical = true
+single_line_exclusions = ['typing']
+order_by_type = false
+group_by_package = true
+skip = [
+    "__init__.py",
+    "third_party"
+]
+
+[tool.pylint.format]
+# Maximum number of characters on a single line.
+max-line-length=100