Skip to content

Commit

Permalink
Add Scaladoc Support (#2689)
Browse files Browse the repository at this point in the history
* add scaladoc.

* remove docs project from base modules.

* include only core module.

* use another submodule.

* comment unidoc filters.

* another try.

* update site workflow.

* remove extra line.

* remove docs from build.
  • Loading branch information
khajavi authored Jan 22, 2023
1 parent 1a669e5 commit c33ac29
Show file tree
Hide file tree
Showing 6 changed files with 162 additions and 47 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ jobs:
strategy:
matrix:
scala: [2.11.12, 2.12.10, 2.13.2, 3.1.2]
module: [base, db, js, async, codegen, bigdata]
module: [docs, base, db, js, async, codegen, bigdata]
include:
- scala: 2.11.12
scala_short: 211
Expand Down
114 changes: 91 additions & 23 deletions .github/workflows/site.yml
Original file line number Diff line number Diff line change
@@ -1,28 +1,96 @@
# This file was autogenerated using `zio-sbt` via `sbt generateGithubWorkflow`
# task and should be included in the git repository. Please do not edit
# it manually.
# This file was autogenerated using `zio-sbt-website` via `sbt generateGithubWorkflow`
# task and should be included in the git repository. Please do not edit it manually.

name: website

on:
name: Website
'on':
workflow_dispatch: {}
release:
types: [ published ]

types:
- published
push:
branches:
- master
pull_request: {}
jobs:
build:
name: Build and Test
runs-on: ubuntu-latest
if: ${{ github.event_name == 'pull_request' }}
steps:
- name: Git Checkout
uses: actions/[email protected]
with:
fetch-depth: '0'
- name: Setup Scala
uses: actions/[email protected]
with:
distribution: temurin
java-version: 17
check-latest: true
- name: Check if the README file is up to date
run: sbt docs/checkReadme
- name: Check if the site workflow is up to date
run: sbt docs/checkGithubWorkflow
- name: Check website build process
run: sbt docs/clean; sbt docs/buildWebsite
publish-docs:
runs-on: ubuntu-20.04
timeout-minutes: 30
name: Publish Docs
runs-on: ubuntu-latest
if: ${{ ((github.event_name == 'release') && (github.event.action == 'published')) || (github.event_name == 'workflow_dispatch') }}
steps:
- uses: actions/[email protected]
with:
fetch-depth: 0
- name: Setup Scala and Java
uses: olafurpg/setup-scala@v13
- uses: actions/setup-node@v3
with:
node-version: '16.x'
registry-url: 'https://registry.npmjs.org'
- name: Publishing Docs to NPM Registry
run: sbt docs/publishToNpm
env:
NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
- name: Git Checkout
uses: actions/[email protected]
with:
fetch-depth: '0'
- name: Setup Scala
uses: actions/[email protected]
with:
distribution: temurin
java-version: 17
check-latest: true
- name: Setup NodeJs
uses: actions/setup-node@v3
with:
node-version: 16.x
registry-url: https://registry.npmjs.org
- name: Publish Docs to NPM Registry
run: sbt docs/publishToNpm
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
generate-readme:
name: Generate README
runs-on: ubuntu-latest
if: ${{ (github.event_name == 'push') || ((github.event_name == 'release') && (github.event.action == 'published')) }}
steps:
- name: Git Checkout
uses: actions/[email protected]
with:
ref: ${{ github.head_ref }}
fetch-depth: '0'
- name: Setup Scala
uses: actions/[email protected]
with:
distribution: temurin
java-version: 17
check-latest: true
- name: Generate Readme
run: sbt docs/generateReadme
- name: Commit Changes
run: |
git config --local user.email "github-actions[bot]@users.noreply.github.com"
git config --local user.name "github-actions[bot]"
git add README.md
git commit -m "Update README.md" || echo "No changes to commit"
- name: Create Pull Request
uses: peter-evans/[email protected]
with:
body: |-
Autogenerated changes after running the `sbt docs/generateReadme` command of the [zio-sbt-website](https://zio.dev/zio-sbt) plugin.
I will automatically update the README.md file whenever there is new change for README.md, e.g.
- After each release, I will update the version in the installation section.
- After any changes to the "docs/index.md" file, I will update the README.md file accordingly.
branch: zio-sbt-website/update-readme
commit-message: Update README.md
delete-branch: true
title: Update README.md
69 changes: 57 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,57 @@
**IMPORTANT: This is the documentation for the latest `SNAPSHOT` version. Please refer to the website at [https://zio.dev/zio-quill](https://zio.dev/zio-quill) for the latest release's documentation.**
[//]: # (This file was autogenerated using `zio-sbt-website` plugin via `sbt generateReadme` command.)
[//]: # (So please do not edit it manually. Instead, change "docs/index.md" file or sbt setting keys)
[//]: # (e.g. "readmeDocumentation" and "readmeSupport".)
<p align="center">
<img src="https://raw.githubusercontent.com/getquill/quill/master/quill.png">
</p>

![quill](https://raw.githubusercontent.com/getquill/quill/master/quill.png)
# ZIO Quill

**Compile-time Language Integrated Query for Scala**
Quill provides a Quoted Domain Specific Language ([QDSL](http://homepages.inf.ed.ac.uk/wadler/papers/qdsl/qdsl.pdf)) to express queries in Scala and execute them in a target language.

[![Build Status](https://travis-ci.org/getquill/quill.svg?branch=master)](https://travis-ci.org/getquill/quill)
[![codecov.io](https://codecov.io/github/getquill/quill/coverage.svg?branch=master)](https://codecov.io/github/getquill/quill?branch=master)
[![Join the chat at https://gitter.im/getquill/quill](https://img.shields.io/badge/gitter-join%20chat-green.svg)](https://gitter.im/getquill/quill?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.getquill/quill-core_2.13/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.getquill/quill-core_2.13)
[![Javadocs](https://www.javadoc.io/badge/io.getquill/quill-core_2.13.svg)](https://www.javadoc.io/doc/io.getquill/quill-core_2.13)
[![Production Ready](https://img.shields.io/badge/Project%20Stage-Production%20Ready-brightgreen.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-quill/workflows/CI/badge.svg) [![Sonatype Releases](https://img.shields.io/nexus/r/https/oss.sonatype.org/io.getquill/quill-core_2.12.svg?label=Sonatype%20Release)](https://oss.sonatype.org/content/repositories/releases/io/getquill/quill-core_2.12/) [![Sonatype Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/io.getquill/quill-core_2.12.svg?label=Sonatype%20Snapshot)](https://oss.sonatype.org/content/repositories/snapshots/io/getquill/quill-core_2.12/) [![javadoc](https://javadoc.io/badge2/io.getquill/zio-quill-docs_2.12/javadoc.svg)](https://javadoc.io/doc/io.getquill/zio-quill-docs_2.12) [![ZIO Quill](https://img.shields.io/github/stars/zio/zio-quill?style=social)](https://github.com/zio/zio-quill)

# Maintainers
## Introduction

The library's core is designed to support multiple target languages, currently featuring specializations for Structured Query Language ([SQL](https://en.wikipedia.org/wiki/SQL)) and Cassandra Query Language ([CQL](https://cassandra.apache.org/doc/latest/cql/)).

1. **Boilerplate-free mapping**: The database schema is mapped using simple case classes.
2. **Quoted DSL**: Queries are defined inside a `quote` block. Quill parses each quoted block of code (quotation) at compile time and translates them to an internal Abstract Syntax Tree (AST)
3. **Compile-time query generation**: The `ctx.run` call reads the quotation's AST and translates it to the target language at compile time, emitting the query string as a compilation message. As the query string is known at compile time, the runtime overhead is very low and similar to using the database driver directly.
4. **Compile-time query validation**: If configured, the query is verified against the database at compile time and the compilation fails if it is not valid. The query validation **does not** alter the database state.

> ### Scala 3 Support
> [ProtoQuill](https://github.com/zio/zio-protoquill) provides Scala 3 support for Quill rebuilding on top of new metaprogramming capabilities from the ground > up! It is published to maven-central as the `quill-<module>_3` line of artifacts.
> ### Doobie Support
> See [here](contexts.md#quill-doobie) for Doobie integration instructions.
## Example

![example](https://raw.githubusercontent.com/getquill/quill/master/example.gif)

Note: The GIF example uses Eclipse, which shows compilation messages to the user.

## Documentation

Learn more on the [ZIO Quill homepage](https://zio.dev/zio-quill)!

## Contributing

For the general guidelines, see ZIO [contributor's guide](https://zio.dev/about/contributing).

## Code of Conduct

See the [Code of Conduct](https://zio.dev/about/code-of-conduct)

## Support

Come chat with us on [![Badge-Discord]][Link-Discord].

[Badge-Discord]: https://img.shields.io/discord/629491597070827530?logo=discord "chat on discord"
[Link-Discord]: https://discord.gg/2ccFBr4 "Discord"

## Maintainers

- @deusaquilus (lead maintainer)
- @fwbrasil (creator)
Expand All @@ -19,7 +60,7 @@
- @mentegy
- @mdedetrich

## Former maintainers:
### Former maintainers:

- @gustavoamigo
- @godenji
Expand All @@ -28,10 +69,14 @@

You can notify all current maintainers using the handle `@getquill/maintainers`.

# Acknowledgments
## Acknowledgement

The project was created having Philip Wadler's talk ["A practical theory of language-integrated query"](http://www.infoq.com/presentations/theory-language-integrated-query) as its initial inspiration. The development was heavily influenced by the following papers:

* [A Practical Theory of Language-Integrated Query](http://homepages.inf.ed.ac.uk/slindley/papers/practical-theory-of-linq.pdf)
* [Everything old is new again: Quoted Domain Specific Languages](http://homepages.inf.ed.ac.uk/wadler/papers/qdsl/qdsl.pdf)
* [The Flatter, the Better](http://db.inf.uni-tuebingen.de/staticfiles/publications/the-flatter-the-better.pdf)
* [The Flatter, the Better](http://db.inf.uni-tuebingen.de/staticfiles/publications/the-flatter-the-better.pdf)

## License

[License](LICENSE)
19 changes: 11 additions & 8 deletions build.sbt
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,10 @@ lazy val baseModules = Seq[sbt.ClasspathDep[sbt.ProjectReference]](
`quill-util`
)

lazy val docsModules = Seq[sbt.ClasspathDep[sbt.ProjectReference]](
docs
)

lazy val dbModules = Seq[sbt.ClasspathDep[sbt.ProjectReference]](
`quill-jdbc`, `quill-doobie`, `quill-jdbc-monix`, `quill-jdbc-zio`
)
Expand All @@ -77,7 +81,7 @@ lazy val bigdataModules = Seq[sbt.ClasspathDep[sbt.ProjectReference]](
)

lazy val allModules =
baseModules ++ jsModules ++ dbModules ++ asyncModules ++ codegenModules ++ bigdataModules
baseModules ++ jsModules ++ dbModules ++ asyncModules ++ codegenModules ++ bigdataModules ++ docsModules

lazy val scala213Modules = baseModules ++ jsModules ++ dbModules ++ codegenModules ++ Seq[sbt.ClasspathDep[sbt.ProjectReference]](
`quill-finagle-mysql`,
Expand Down Expand Up @@ -1036,19 +1040,18 @@ lazy val releaseSettings = Seq(
lazy val docs = project
.in(file("zio-quill-docs"))
.settings(
publish / skip := true,
moduleName := "zio-quill-docs",
scalacOptions -= "-Yno-imports",
scalacOptions -= "-Xfatal-warnings",
scalacOptions += "-Xlog-implicits",
libraryDependencies ++= Seq("dev.zio" %% "zio" % Version.zio),
projectName := "ZIO Quill",
badgeInfo := Some(
BadgeInfo(
artifact = "quill-core_2.12",
projectStage = ProjectStage.ProductionReady
)
),
mainModuleName := (`quill-core-jvm` / moduleName).value,
// ScalaUnidoc / unidoc / unidocProjectFilter := inProjects(
// `quill-engine-jvm`,
// ),
projectStage := ProjectStage.ProductionReady,
checkArtifactBuildProcessWorkflowStep := None,
docsPublishBranch := "master",
readmeBanner :=
"""|<p align="center">
Expand Down
1 change: 1 addition & 0 deletions build/release.sh
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ then
if [[ $ARTIFACT == "async" ]]; then $SBT_VER -Dmodules=async publish; fi
if [[ $ARTIFACT == "codegen" ]]; then $SBT_VER -Dmodules=codegen publish; fi
if [[ $ARTIFACT == "bigdata" ]]; then $SBT_VER -Dmodules=bigdata publish; fi
if [[ $ARTIFACT == "docs" ]]; then $SBT_VER -Dmodules=docs publish; fi

# No-Op Publish
if [[ $ARTIFACT == "publish" ]]; then echo "No-Op Publish for Non Release Snapshot Branch"; fi
Expand Down
4 changes: 1 addition & 3 deletions project/plugins.sbt
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,4 @@ addSbtPlugin("org.portable-scala" % "sbt-scalajs-crossproject" % "1.2.0")

addSbtPlugin("com.etsy" % "sbt-compile-quick-plugin" % "1.4.0")

addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.2.2")

resolvers += Resolver.sonatypeRepo("public")
addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.3.9")

0 comments on commit c33ac29

Please sign in to comment.