reinitialize repo

.dockerignore

@@ -0,0 +1,20 @@
+*
+**/__pycache__/
+
+!app.py
+!config.yml
+!gunicorn_config.py
+!Procfile
+!requirements.txt
+!environment/.env
+!environment/settings.py
+
+!builtin/
+
+!assets/
+!call/
+!components/
+!layout/
+!markdown/
+!pages/
+!utils/

.flake8

@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 88
+extend-ignore = E203

.github/workflows/release-please.yml

@@ -0,0 +1,16 @@
+
+on:
+  push:
+    branches:
+      - main
+name: release-please
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: google-github-actions/release-please-action@v3
+        with:
+          release-type: python
+          package-name: release-please-action
+          bump-minor-pre-major: true
+          extra-files: builtin/version.py CITATION.cff

.gitignore

@@ -0,0 +1,22 @@
+**/__pycache__/
+*.log
+.sgex.log*
+
+/.env
+/.venv/
+/.venv-dev/
+
+/config.yml
+data/
+secrets/
+environment/*
+!environment/settings.py
+
+# delete this group of lines to track custom content in git
+assets/*
+call/*
+components/*
+layout/*
+markdown/*
+pages/*
+utils/*

.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: check-json
+    -   id: check-added-large-files
+    -   id: requirements-txt-fixer
+-   repo: https://github.com/PyCQA/isort
+    rev: 5.11.4
+    hooks:
+    -   id: isort
+-   repo: https://github.com/python/black
+    rev: 22.12.0
+    hooks:
+    -   id: black
+-   repo: https://github.com/PyCQA/flake8
+    rev: 6.0.0
+    hooks:
+    -   id: flake8
+-   repo: https://github.com/PyCQA/bandit
+    rev: 1.7.4
+    hooks:
+    -   id: bandit

.vscode/launch.json

@@ -0,0 +1,25 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: App",
+            "type": "python",
+            "request": "launch",
+            "program": "app.py",
+            "console": "integratedTerminal",
+            "env": {
+                "ENVIRONMENT_FILE": ".env.dev"
+            }
+        },
+        {
+            "name": "Python: Current File",
+            "type": "python",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "env": {
+                "ENVIRONMENT_FILE": ".env.dev"
+            }
+        }
+    ]
+}

CITATION.cff

@@ -0,0 +1,12 @@
+
+cff-version: 1.2.0
+message: "If you this software, please cite it as below."
+authors:
+   - family-names: Isaacs
+     given-names: Loryn
+     orcid: "https://orcid.org/0000-0003-0267-4853"
+title: "Quartz"
+version: 0.1.0 # x-release-please-version
+date-released: 2023-01-21
+repository-code: https://github.com/engisalor/quartz
+license: GPLv3+

Dockerfile

@@ -0,0 +1,16 @@
+FROM docker.io/library/python:3.11-slim-bullseye
+
+WORKDIR /code
+
+COPY requirements.txt /
+
+RUN pip install -r /requirements.txt \
+	&& rm -rf /root/.cache
+
+COPY ./ ./
+
+ENV ENVIRONMENT_FILE=".env"
+
+EXPOSE 8080
+
+ENTRYPOINT ["gunicorn", "--config", "gunicorn_config.py", "app:server"]

Makefile

@@ -0,0 +1,49 @@
+# NoSkE commands based on https://github.com/ELTE-DH/NoSketch-Engine-Docker
+
+# set current variables
+include .env
+
+
+get_started:
+# populates working dir with files for a new project
+	cp -i builtin/config/config.yml config.yml
+	cp -i builtin/config/environment.env environment/.env
+	cp -i builtin/config/environment.env.dev environment/.env.dev
+	mkdir assets call components layout markdown pages utils
+
+
+noske:
+# starts noske container
+	docker run -d --rm --name noske -p 10070:80 \
+	--mount type=bind,src=$(CORPORA_DIR),dst=/corpora \
+    $(NOSKE_IMAGE)
+	@echo 'URL: http://localhost:10070/'
+.PHONY: noske
+
+
+quartz:
+# starts quartz container
+	docker run -d --rm --name quartz -p 8080:8080 \
+	--mount type=bind,src=$(QUARTZ_DIR),dst=/data \
+    $(QUARTZ_IMAGE)
+	@echo 'URL: http://localhost:8080/'
+.PHONY: quartz
+
+
+connect:
+# connects to container via bash
+	docker exec -it noske /bin/bash
+.PHONY: connect
+
+
+execute:
+# executes noske command
+	docker run --rm -it --mount type=bind,src=$(CORPORA_DIR),dst=/corpora \
+     $(NOSKE_IMAGE) "$(CMD)"
+.PHONY: execute
+
+
+compile:
+# compiles one corpus
+	@read -p "Corpus: " CORPUS; make execute CMD="compilecorp --no-ske --recompile-corpus $$CORPUS"
+.PHONY: compile_one

Procfile

@@ -0,0 +1 @@
+web: gunicorn app:server

README.md

@@ -0,0 +1,104 @@
+# Quartz
+
+*- Under construction -*
+
+Quartz is a dashboard for visualizing corpus data from Sketch Engine servers. It's built with Python and Plotly's Dash framework and is deployable as a Docker container.
+
+To use Quartz you'll need a compiled Sketch Engine corpus (if using locally) and/or API access to a Sketch Engine server (for making external queries). This repo is oriented toward developers and researchers wanting to automate data visualization and prepare customizable apps for corpus linguistics.
+
+Quartz is designed as an application template to allow for easy adaptation, though it can be used as-is with its built-in visualizations. These features are meant to be a common resource for developing corpus visualization methods (contributions are welcome). Some modifications may be needed depending on how your data is structured.
+
+## Installation
+
+Get started by cloning/forking this repo. Also check out these links for information on each software dependency:
+
+- [Sketch Engine](https://www.sketchengine.eu/)
+- [NoSketch Engine](https://nlp.fi.muni.cz/trac/noske)
+- [NoSketch Engine Docker](https://github.com/ELTE-DH/NoSketch-Engine-Docker)
+- [Sketch Grammar Explorer](https://github.com/engisalor/sketch-grammar-explorer)
+- [Plotly graphing library](https://plotly.com/python/)
+- [Dash web app framework](https://dash.plotly.com/)
+- [Docker containerization](https://www.docker.com/)
+
+### Get started
+
+Run the following snippet to copy default configuration files. Modify these files as needed to fit your project.
+
+```bash
+cp -i builtin/config/.env .env-test
+make get_started
+```
+
+#### Environment variables
+
+Environment variables are managed in these files.
+
+- `.env` is for `docker-compose` variables
+- `environment/.env` is for production environments
+- `environment/.env.dev` is for development/running Quartz as a standalone Flask app
+- the development environment activates automatically for VScode users via `.vscode/launch.json`
+
+#### Virtual environments
+
+Add a Python virtual environment for Quartz dependencies and another for development purposes if you plan to contribute to Quartz.
+
+```bash
+# for Quartz
+python3 -m venv .venv
+source $PWD/.venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+
+# for development
+python3 -m venv .venv-dev
+source $PWD/.venv-dev/bin/activate
+pip install --upgrade pip
+pip install pre-commit
+pip install -r requirements.txt
+pre-commit install
+```
+
+#### SGEX config
+
+Quartz uses the SGEX Python package for making Sketch Engine API requests. This requires a `config.yml` file with server names and settings (see SGEX documentation for details). By default, `make get_started` settings only work with a local NoSkE server.
+
+### Build images
+
+Run `docker-compose build` to build a Quartz image and pull the NoSketch Engine Docker image.
+
+### Run NoSketch Engine
+
+Before starting Quartz, run `make noske` to start NoSketch Engine. Be aware that the container may not work if the `CORPORA_DIR` path isn't correct, is empty, or has invalid corpus files. See the NoSketch Engine Docker repo listed earlier for more guidance.
+
+Run `docker stop noske` to stop the container.
+
+### Run Quartz
+
+#### With Gunicorn
+
+Quartz can run like any normal Flask web app as long as `ENVIRONMENT_FILE` is set first: run `ENVIRONMENT_FILE=.env.dev python3 app.py`. VScode users can press `F5` to start the app with debugging enabled.
+
+#### With docker
+
+Run `make quartz` to start Quartz, and to stop the container run `docker stop quartz`.
+
+### Developing Quartz
+
+#### Notes 
+
+- 
+- `.dockerignore` excludes everything by default
+
+## About
+
+Quartz was developed with funding from the [Humanitarian Encyclopedia](https://humanitarianencyclopedia.org) and support from the University of Granada's [LexiCon research group](http://lexicon.ugr.es).
+
+Quartz is possible thanks to the work of [Lexical Computing](https://www.lexicalcomputing.com/), researchers who've [contributed to Sketch Engine](https://www.sketchengine.eu/bibliography-of-sketch-engine/), and the Dockerized version by the Eötvös Loránd University Department of Digital Humanities. NoSketch Engine is available under [GPL licenses](https://nlp.fi.muni.cz/trac/noske).
+
+This app includes [Dash Bootstrap Components](https://dash-bootstrap-components.opensource.faculty.ai/) and its Docker implementation is based on [this template](https://github.com/CzakoZoltan08/dash-clean-architecture-template). [Dash's community forum](https://community.plotly.com/) also deserves thanks.
+
+The name Quartz is a nod to Sketch Engine's GUI, Crystal.
+
+## Citation
+
+If you use Quartz, please [cite it](/CITATION.cff).

app.py

@@ -0,0 +1,35 @@
+import importlib
+
+import dash
+import dash_bootstrap_components as dbc
+import flask
+from dash import html
+
+import environment.settings as env
+
+
+
+layout = importlib.import_module(env.LAYOUT_MODULE)
+server = flask.Flask(__name__)
+
+app = dash.Dash(
+    __name__,
+    use_pages=True,
+    pages_folder=env.PAGES_DIR,
+    server=server,
+    suppress_callback_exceptions=True,
+    assets_ignore=".*ignore.*",
+    assets_folder=env.ASSETS_DIR,
+    external_stylesheets=[
+        dbc.themes.CERULEAN,
+        dbc.icons.FONT_AWESOME,
+        "https://codepen.io/chriddyp/pen/dZVMbK.css",
+    ],
+    meta_tags=[{"name": "viewport", "content": "width=device-width, initial-scale=1"}],
+)
+
+app.layout = html.Div([layout.sidebar(), layout.content])
+
+
+if __name__ == "__main__":
+    app.run(host=env.HOST, port=env.PORT, debug=env.DASH_DEBUG, dev_tools_hot_reload=False)

builtin/assets/0-typography.css

@@ -0,0 +1,7 @@
+/* Override Dash font to use Cerulean: refer to https://cdn.jsdelivr.net/npm/[email protected]/dist/cerulean/bootstrap.css */
+* {
+    font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", "Liberation Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+}
+
+h1, h2, h3, h4, h5, h6 {
+    color: #5065A8; }