Skip to content
Permalink
Browse files

Add MkDocs Material + Dokka powered docs site

* Inspired liberally by existing MkDocs sites in OkHttp and Barber
* MkDocs really chugs generating the site for this many Dokka generated docs so it takes some patience if you want to build the docs site locally (2-5 mins to build instead of near instantly with other repos)
* There are numerous warnings from MkDocs of dead links in the Dokka generated content. This PR makes no changes to the existing docs in Misk projects. Future PRs should.
* [CLOSES #1148]
  • Loading branch information...
adrw committed Aug 15, 2019
1 parent 226c5f7 commit d647a32aeca3db10d54016887967ae70a2b5b9ab
@@ -109,6 +109,33 @@ jobs:
steps:
- checkout
- run: sudo npm install -g @misk/cli && miskweb ci-build -e
docs:
machine:
image: circleci/classic:latest
parallelism: 1
steps:
- checkout # check out source code to working directory
- run: |
sudo mkdir -p /usr/local/bin
sudo chown -R circleci:circleci /usr/local/bin
- run: |
sudo mkdir -p /usr/local/lib/python3.6/site-packages
sudo chown -R circleci:circleci /usr/local/lib/python3.6/site-packages
- restore_cache:
key: pipdeps-{{ .Branch }}
- run: sudo pip install mkdocs mkdocs-material
- save_cache:
key: pipdeps-{{ .Branch }}
paths:
- "/usr/local/bin"
- "/usr/local/lib/python3.6/site-packages"
- run: |
./gradlew dokka
- run: |
cat README.md | grep -v 'project website' > docs/index.md
cp CHANGELOG.md docs/changelog.md
cp RELEASING.md docs/releasing.md
- run: mkdocs build
workflows:
version: 2
on_commit:
@@ -119,10 +146,12 @@ workflows:
only: master
- java
- node
- docs
nightly:
jobs:
- java
- node
- docs
triggers:
- schedule:
# midnight mountain time in UTC
@@ -21,3 +21,9 @@ dist
.hash
hooks.gradle
repositories.gradle

**/site/
docs/0.x/*
docs/index.md
docs/changelog.md
docs/releasing.md
@@ -4,7 +4,8 @@ Change Log
Version 0.2.5 *(2018-06-11)*
----------------------------

New:
### New

* Cluster interface and DataSourceCluster bindings
* Add a JPAEntityModule for binding entities for a DataSource
* Hook up raw Hibernate APIs
@@ -34,7 +35,8 @@ New:
* Misk containers should not run as root
* DbTimestampedEntity

Fix:
### Fix

* Don't inject until after services are started.
* Tidy up some test cases.
* Fix a missing dependency in exemplar
@@ -43,7 +45,8 @@ Fix:
Version 0.2.4 *(2018-05-14)*
----------------------------

New:
### New

* Add support for protobuf over HTTP
* Cloudwatch Trail logging support
* Add retry() helper
@@ -52,31 +55,35 @@ New:
* Adds a DataSourceModule
* Add support for logging to StackDriver

Fix:
### Fix

* Move static resources from web root into resources
* Move web-specific NetworkInterceptor into web
* Remove use of instance metadata endpoints

Version 0.2.3 *(2018-04-27)*
----------------------------

New:
### New

* Add kubernetes java client so that hosts can know their peers
* Use EventRouter for exemplarchat. Add a static resource mapper
* Create a cluster wide admin healthcheck page
* Change CacheBuilder to be mapOf since no concurrency
* Adds a healthcheck for the kubernetes client
* Adds a local cluster connector so that development functions

Fix:
### Fix

* Don't treat assembly as a release when running in CI
* Fix tracing startup when none is configured
* Various event router fixes and refactorings

Version 0.2.1 *(2018-03-26)*
----------------------------

New:
### New

* Remove unnecessary check from uploadArchives task (#149)
* Add a RELEASING.md to outline misk release process (#150)
* Move chat into its own example project. (#146)
@@ -89,13 +96,15 @@ New:
* More tests to exercise EventRouter behaviors. (#158)
* Support loading keystores from combined private key and certificate chain PEM files (#157)

Fix:
### Fix

* Fix event router tests (#159)

Version 0.2.0 *(2018-03-13)*
----------------------------

New:
### New

* Add \_status action
* Split Interceptor into NetworkInterceptor and ApplicationInterceptor
* Introduce websocket support in misk
@@ -115,7 +124,8 @@ New:
* Allow customized exception mappings
* Add support for query strings in urls

Fix:
### Fix

* Eliminate redundant \_config suffix in config files
* Support Web actions that return Nothing
* Use proper snake-casing for default property names
@@ -1,25 +1,14 @@
<img src="misk.png" width="300">
<img src="https://github.com/cashapp/misk/raw/master/misk.png" width="300">

Misk is a new open source application container from Square.
See the [project website][misk] for documentation and APIs.

Looking for `@misk/` NPM Packages? **Check out [Misk-Web](https://github.com/square/misk-web)**
Misk is a new open source application container from Cash App.

Misk is not ready for use. The API is not stable.

Quick Links
===
## Looking for Misk-Web?
Misk-Web powers the Misk Admin Dashboard with modular Typescript + React powered tabs.
**Check out [Misk-Web][miskweb]!**

Web
---
- [General Info on Misk Admin Dashboard / Web](https://github.com/square/misk-web/blob/master/README.md)
- [Developing a New Tab Guide](https://github.com/square/misk-web/blob/master/HOWTO.md)
- [Template Exemplar Web Tab](https://github.com/square/misk-web/tree/master/examples)

[Recommended Workflow](https://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow/)
---
1. Fork into your personal Github account
1. Clone repo from your fork
1. Add square as a remote with `git remote add cashapp git@github.com:cashapp/misk.git`
1. Pull any new changes with `git pull cashapp master`
1. Push any new changes to a new branch in your personal fork
1. Open PR from personal fork -> cashapp/master
[misk]: https://cashapp.github.io/misk/
[miskweb]: https://cashapp.github.io/misk-web/
@@ -1,44 +1,105 @@
Releasing
-------------
=========

The upload isn't idempotent, so if you're uploading multiple artifacts and it fails partway,
you'll need to invoke the uploadArchives command for each remaining artifact.
### Prerequisite: Sonatype (Maven Central) Account

Release the base `misk/misk` subproject with command below from the main `cash/misk` directory.
Create an account on the [Sonatype issues site][sonatype_issues]. Ask an existing publisher to open
an issue requesting publishing permissions for `misk` projects.

```
$ ./gradlew misk:uploadArchives -Pinternal
### Prerequisite: GPG Keys

```
Generate a GPG key (RSA, 4096 bit, 3650 day) expiry, or use an existing one. You should leave the
password empty for this key.

Release a specific misk subproject with `./gradlew { misk-subproject }:uploadArchives -Pinternal`. Example for `misk-aws` below.
```
$ gpg --full-generate-key
```

```
$ ./gradlew misk-aws:uploadArchives -Pinternal
Upload the GPG keys to public servers:

```
```
$ gpg --list-keys --keyid-format LONG
/Users/johnbarber/.gnupg/pubring.kbx
------------------------------
pub rsa4096/XXXXXXXXXXXXXXXX 2019-07-16 [SC] [expires: 2029-07-13]
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
uid [ultimate] John Barber <jbarber@cash.app>
sub rsa4096/ZZZZZZZZZZZZZZZZ 2019-07-16 [E] [expires: 2029-07-13]
Release all misk subprojects with command below from the main `cash/misk` directory.
$ gpg --send-keys --keyserver keyserver.ubuntu.com XXXXXXXXXXXXXXXX
```

```
$ ./gradlew uploadArchives -Pinternal
```
### Prerequisite: Gradle Properties

If base `misk/misk` subproject or other artifacts have already been published, any of the above commands will fail. You will then need to manually `uploadArchives` for all subprojects.
Note: the below command may not be up to date with all of the current Misk subprojects.
Define publishing properties in `~/.gradle/gradle.properties`:

```
$ ./gradlew misk:uploadArchives -Pinternal && \
./gradlew misk-aws:uploadArchives -Pinternal && \
./gradlew misk-eventrouter:uploadArchives -Pinternal && \
./gradlew misk-events:uploadArchives -Pinternal && \
./gradlew misk-gcp:uploadArchives -Pinternal && \
./gradlew misk-gcp-testing:uploadArchives -Pinternal && \
./gradlew misk-grpc-tests:uploadArchives -Pinternal && \
./gradlew misk-hibernate:uploadArchives -Pinternal && \
./gradlew misk-hibernate-testing:uploadArchives -Pinternal && \
./gradlew misk-jaeger:uploadArchives -Pinternal && \
./gradlew misk-prometheus:uploadArchives -Pinternal && \
./gradlew misk-testing:uploadArchives -Pinternal && \
./gradlew misk-zipkin:uploadArchives -Pinternal
```
```
signing.keyId=1A2345F8
signing.password=
signing.secretKeyRingFile=/Users/jwilson/.gnupg/secring.gpg
```

`signing.keyId` is the GPG key's ID. Get it with this:

```
$ gpg --list-keys --keyid-format SHORT
```

`signing.password` is the password for this key. This might be empty!

`signing.secretKeyRingFile` is the absolute path for `secring.gpg`. You may need to export this
file manually with the following command where `XXXXXXXX` is the `keyId` above:

```
$ gpg --keyring secring.gpg --export-secret-key XXXXXXXX > ~/.gnupg/secring.gpg
```


Cutting a Release
-----------------

1. Update `CHANGELOG.md`.

2. Set versions:

```
export RELEASE_VERSION=X.Y.Z
export NEXT_VERSION=X.Y.Z-SNAPSHOT
```

3. Set environment variables with your [Sonatype credentials][sonatype_issues].

```
export SONATYPE_NEXUS_USERNAME=johnbarber
export SONATYPE_NEXUS_PASSWORD=`pbpaste`
```

4. Update, build, and upload:

```
sed -i "" \
"s/VERSION_NAME=.*/VERSION_NAME=$RELEASE_VERSION/g" \
gradle.properties
sed -i "" \
"s/\"misk:\([^\:]*\):[^\"]*\"/\"misk:\1:$RELEASE_VERSION\"/g" \
`find . -name "README.md"`
./gradlew clean uploadArchives
```

5. Visit [Sonatype Nexus][sonatype_nexus] to promote (close then release) the artifact. Or drop it
if there is a problem!

6. Tag the release, prepare for the next one, and push to GitHub.

```
git commit -am "Prepare for release $RELEASE_VERSION."
git tag -a misk-$RELEASE_VERSION -m "Version $RELEASE_VERSION"
sed -i "" \
"s/VERSION_NAME=.*/VERSION_NAME=$NEXT_VERSION/g" \
gradle.properties
git commit -am "Prepare next development version."
git push && git push --tags
```

[sonatype_issues]: https://issues.sonatype.org/
[sonatype_nexus]: https://oss.sonatype.org/
@@ -42,6 +42,7 @@ tasks.register("testShardHibernate") {
subprojects {
apply plugin: 'java'
apply plugin: 'kotlin'
apply plugin: 'org.jetbrains.dokka'
apply plugin: 'com.diffplug.gradle.spotless'

buildscript {
@@ -86,6 +87,17 @@ subprojects {
testImplementation dep.junitApi
testRuntimeOnly dep.junitEngine
}

// We have to set the dokka configuration after evaluation since the com.vanniktech.maven.publish
// plugin overwrites our dokka configuration on projects where it's applied.
afterEvaluate { p ->
p.tasks.dokka {
reportUndocumented = false
skipDeprecated = true
jdkVersion = 8
}
}

test {
useJUnitPlatform()
testLogging {
@@ -0,0 +1,37 @@
#!/bin/bash

# The website is built using MkDocs with the Material theme.
# https://squidfunk.github.io/mkdocs-material/
# It requires Python to run.
# Install the packages with the following command:
# pip install mkdocs mkdocs-material

set -ex

REPO="git@github.com:cashapp/misk.git"
DIR=temp-clone

# Delete any existing temporary website clone
rm -rf $DIR

# Clone the current repo into temp folder
git clone $REPO $DIR

# Move working directory into temp folder
cd $DIR

# Generate the API docs
GRADLE_TASKS=$(ls -d misk*/ | cut -f1 -d'/' | awk '{ printf ":%s:dokka ", $1 }')
./gradlew dokka

# Copy in special files that GitHub wants in the project root.
cat README.md | grep -v 'project website' > docs/index.md
cp CHANGELOG.md docs/changelog.md
cp RELEASING.md docs/releasing.md

# Build the site and push the new files up to GitHub
mkdocs gh-deploy

# Delete our temp folder
cd ..
rm -rf $DIR

0 comments on commit d647a32

Please sign in to comment.
You can’t perform that action at this time.