Skip to content

Commit

Permalink
WIP: Betterdocs (#206)
Browse files Browse the repository at this point in the history
* Added all hackage links

* Added installation instructions, symlinked to docs

* Polish docs

* Fixed licence and author and github locations

* Renamed project on main README

* Clean up docs

* Updated readme links in haddocks

* Fix broken link

* Changed font
  • Loading branch information
kejace authored Feb 7, 2020
1 parent 601fd05 commit 9a1c8af
Show file tree
Hide file tree
Showing 33 changed files with 164 additions and 217 deletions.
67 changes: 67 additions & 0 deletions INSTALL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
title: Installation
---

## Build

### Prerequisites

#### stack
At the moment the project's build is managed by `stack`. You can find everything you need regarding how to install stack on your machine [here](https://docs.haskellstack.org/en/stable/README/).

#### protoc
We use a custom setup to generate Haskell bindings to the protobuf files, using the proto-lens library from Google. In order for this to work you need to have the protobuf compiler `protoc` on your machine. You can get installation instructions [here](https://google.github.io/proto-lens/installing-protoc.html)

#### libsecp256k1
In order to build with stack you will need this. On MacOS you can use brew:

```
> brew tap cuber/homebrew-libsecp256k1
> brew install libsecp256k1
```

On linux:

```
> sudo add-apt-repository ppa:tah83/secp256k1
> sudo apt-get update
> sudo apt-get install libsecp256k1
```

#### style
You will also need to install `hlint` and `stylish-haskell` for code hygiene during development. In the project root simply run

```bash
> stack install hlint stylish-haskell
```

### Commands
There is a `Makefile` for this project where you can find all of the options for building, testing etc. The `Makefile`
is documented and there is a help menu which you can access via the commands `make` or `make help`.

## Protobuf Files and Generated Modules
The protobuf files are all in the `/protos` directory, and we use a custom setup in order
to generate the corresponding `Proto.*` Haskell modules. If you want to view all of these
generated modules, you can run

```bash
> find hs-abci-types/.stack-work -path '*autogen/Proto'
```

to find the root directory.

## Style Guide
There is a `.stylish-haskell.yaml` file that controls some of the style guide, particularly
around import statements and some indentation rules. There is also a small guide for things that
fall outside of this in the [style wiki](https://github.com/f-o-a-m/kepler/wiki/code-style-guide).
If it's not covered by either of these but you think it's really important, mention it in an issue.

## Building documentation
You can build the haddocks for the library code only using

```bash
make build-docs-local
```

This does not build and link documentation for dependencies, useful mostly for testing
documentation formatting.
8 changes: 4 additions & 4 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ stylish: ## Run stylish-haskell over all haskell projects
find ./hs-abci-types \
./hs-abci-extra \
./hs-tendermint-client \
./hs-abci-examples \
./hs-abci-docs \
./hs-abci-sdk \
./hs-abci-test-utils \
./hs-abci-server \
Expand Down Expand Up @@ -80,13 +80,13 @@ test-iavl-client: ## test the iavl client library basic operation (requires grpc
#####################

deploy-simple-storage-docker: install ## run the simple storage docker network
docker-compose -f hs-abci-examples/simple-storage/docker-compose.yaml up --build
docker-compose -f hs-abci-docs/simple-storage/docker-compose.yaml up --build

deploy-nameservice: install ## run the nameservice docker network with elk stack for logging
docker-compose -f hs-abci-examples/nameservice/docker-compose.yaml up --build
docker-compose -f hs-abci-docs/nameservice/docker-compose.yaml up --build

deploy-nameservice-test: install ## run the nameservice docker network for testing
docker-compose -f hs-abci-examples/nameservice/docker-compose-test.yaml up --build
docker-compose -f hs-abci-docs/nameservice/docker-compose-test.yaml up --build


#####################
Expand Down
68 changes: 4 additions & 64 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,74 +1,14 @@
# hs-abci
# kepler

[![Build Status](https://travis-ci.com/f-o-a-m/hs-abci.svg?branch=master)](https://travis-ci.com/f-o-a-m/hs-abci)
[![Build Status](https://travis-ci.com/f-o-a-m/kepler.svg?branch=master)](https://travis-ci.com/f-o-a-m/kepler)

## Introduction
This is the official repository for the Haskell implementation of the ABCI server and
SDK for developing applications backed by the Tendermint replication engine. You can
read more about Tendermint and the ABCI specs in their [documentation](https://tendermint.com/docs/spec/abci/).

To understand how to build a simple application using this library, see the literate haskell [walkthrough](https://github.com/f-o-a-m/hs-abci/blob/master/hs-abci-examples/nameservice/README.md).
To understand how to build a simple application using this library, see the literate haskell [walkthrough](https://github.com/f-o-a-m/kepler/blob/master/hs-abci-docs/nameservice/README.md).

## Build

### Prerequisites

#### stack
At the moment the project's build is managed by `stack`. You can find everything you need regarding how to install stack on your machine [here](https://docs.haskellstack.org/en/stable/README/).

#### protoc
We use a custom setup to generate Haskell bindings to the protobuf files, using the proto-lens library from Google. In order for this to work you need to have the protobuf compiler `protoc` on your machine. You can get installation instructions [here](https://google.github.io/proto-lens/installing-protoc.html)

#### libsecp256k1
In order to build with stack you will need this. On MacOS you can use brew:

```
> brew tap cuber/homebrew-libsecp256k1
> brew install libsecp256k1
```

On linux:

```
> sudo add-apt-repository ppa:tah83/secp256k1
> sudo apt-get update
> sudo apt-get install libsecp256k1
```

#### style
You will also need to install `hlint` and `stylish-haskell` for code hygiene during development. In the project root simply run

```bash
> stack install hlint stylish-haskell
```

### Commands
There is a `Makefile` for this project where you can find all of the options for building, testing etc. The `Makefile`
is documented and there is a help menu which you can access via the commands `make` or `make help`.

## Protobuf Files and Generated Modules
The protobuf files are all in the `/protos` directory, and we use a custom setup in order
to generate the corresponding `Proto.*` Haskell modules. If you want to view all of these
generated modules, you can run

```bash
> find hs-abci-types/.stack-work -path '*autogen/Proto'
```

to find the root directory.

## Style Guide
There is a `.stylish-haskell.yaml` file that controls some of the style guide, particularly
around import statements and some indentation rules. There is also a small guide for things that
fall outside of this in the [style wiki](https://github.com/f-o-a-m/hs-abci/wiki/code-style-guide).
If it's not covered by either of these but you think it's really important, mention it in an issue.

## Building documentation
You can build the haddocks for the library code only using

```bash
make build-docs-local
```

This does not build and link documentation for dependencies, useful mostly for testing
documentation formatting.
See [installation instructions](https://github.com/f-o-a-m/kepler/blob/master/INSTALL.md)
6 changes: 3 additions & 3 deletions hs-abci-docs/.tintin.yml
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
name: kepler
synopsis: Haskell Cosmos SDK
github: f-o-a-m/kepler
author: Martin Allen
author: f-o-a-m
authorWebsite: https://foam.space
color: #5E5184
#logo: https://pbs.twimg.com/profile_images/791467713956839424/pBRQn1wt_400x400.jpg
titleFont: Poiret One
titleFont: Lora
titleFontWeight: 400
bodyFont: PT Sans
bodyFont: Open Sans
5 changes: 5 additions & 0 deletions hs-abci-docs/doc/0010-Overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
title: Overview
---

The documentation consists of an overview, foundations, a tutorial called ` nameservice` as well as documentation of logging and metrics. You can navigate to the relevant sections on the left side.
1 change: 1 addition & 0 deletions hs-abci-docs/doc/0020-Installation.md
File renamed without changes.
18 changes: 8 additions & 10 deletions hs-abci-docs/doc/98-Logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Logging

# Logging

The SDK has built in support for structured logging via the [katip](https://hackage.haskell.org/package/katip) logging library. Even still, the SDK is agnostic to where you want your logs to go. Katip logs are managed by *scribes* whos job is precisely this, so the output depends on which scribes you use. The two most common scribes are the [console scribe](https://hackage.haskell.org/package/katip-0.8.3.0/docs/Katip-Scribes-Handle.html#v:mkHandleScribe) and the [Elasticsearch scribe](https://hackage.haskell.org/package/katip-elasticsearch).
The SDK has built in support for structured logging via the [katip](https://hackage.haskell.org/package/katip) logging library. Even still, the SDK is agnostic to where you want your logs to go. Katip logs are managed by *scribes* whose job is precisely this, so the output depends on which scribes you use. The two most common scribes are the [console scribe](https://hackage.haskell.org/package/katip-0.8.3.0/docs/Katip-Scribes-Handle.html#v:mkHandleScribe) and the [Elasticsearch scribe](https://hackage.haskell.org/package/katip-elasticsearch).

The `Nameservice` application has support for either scribe -- it will use Elasticsearch if you provide the `ES_HOST` and `ES_PORT` environment variables or otherwise will default to console logging. The docker deployment is configured to use Elasticsearch.

Expand All @@ -14,19 +14,19 @@ The docker network includes an `elk` image (Elasticsearch, Logstash, Kibana) for

When logging to Elasticsearch, you can use the Kibana dashboard for creating queries and visualizations. We will cover the basics here. If you have already launched the docker network, you can view the Kibana dashboard by going to http://localhost:5601/app/kibana. You should see something like

<img src="https://raw.githubusercontent.com/f-o-a-m/hs-abci/master/hs-abci-examples/nameservice/images/kibana_welcome_screen.png" width="50%"/>
<img src="https://raw.githubusercontent.com/f-o-a-m/kepler/master/hs-abci-docs/nameservice/images/kibana_welcome_screen.png" width="50%"/>

To create an index (a searchable pattern), click on the *Management* tab, click *Create Index*, and enter `nameservice` as the pattern. You should see something like this:

<img src="https://raw.githubusercontent.com/f-o-a-m/hs-abci/master/hs-abci-examples/nameservice/images/kibana_management.png" width="50%"/>
<img src="https://raw.githubusercontent.com/f-o-a-m/kepler/master/hs-abci-docs/nameservice/images/kibana_management.png" width="50%"/>

You can ignore the advanced options, e.g. time filter, for now:

<img src="https://raw.githubusercontent.com/f-o-a-m/hs-abci/master/hs-abci-examples/nameservice/images/kibana_management_2.png" width="50%"/>
<img src="https://raw.githubusercontent.com/f-o-a-m/kepler/master/hs-abci-docs/nameservice/images/kibana_management_2.png" width="50%"/>

To view and search the logs, you can click the `Discover` tab. You should see all of the logs in the resulting search, from both server and application:

<img src="https://raw.githubusercontent.com/f-o-a-m/hs-abci/master/hs-abci-examples/nameservice/images/kibana_discover.png" width="50%"/>
<img src="https://raw.githubusercontent.com/f-o-a-m/kepler/master/hs-abci-docs/nameservice/images/kibana_discover.png" width="50%"/>

## Searching a Log Index

Expand All @@ -38,19 +38,19 @@ The log structure is effectively a JSON object (with nesting). There are a few f
- `message_hash`: the SHA256 of the protobuf encoded bytes for the abci message that caused the logs.
- `ns` (namespace): a list of increasingly specific scopes for where the log originated. In this case, `nameservice` is the root namespace, `server` or `application` is the next scope.

Remember that the basic lifescycle of an `ABCI` message is that it first comes to the ABCI-server from tendermint, is then handed off to your application for processing, and finally the response is sent from the ABCI-server back to tendermint. In order to better track this lifecycle, we highly recommend you use the [logging middleware](https://github.com/f-o-a-m/hs-abci/blob/master/hs-abci-extra/src/Network/ABCI/Server/Middleware/Logger.hs). This middleware will attach the `message_type` and `message_hash` to the context for every single log that is produced, meaning that you can get a trace for a given message by simply searching its hash.
Remember that the basic lifescycle of an `ABCI` message is that it first comes to the ABCI-server from tendermint, is then handed off to your application for processing, and finally the response is sent from the ABCI-server back to tendermint. In order to better track this lifecycle, we highly recommend you use the [logging middleware](https://github.com/f-o-a-m/kepler/blob/master/hs-abci-extra/src/Network/ABCI/Server/Middleware/Logger.hs). This middleware will attach the `message_type` and `message_hash` to the context for every single log that is produced, meaning that you can get a trace for a given message by simply searching its hash.

### Querying the Logs

You can create custom search filters in the *Discover* tab, just click the *Add a filter* button near the search bar. For example, we can filter all of the logs for those that correspond to a *deliverTx* message:

<img src="https://raw.githubusercontent.com/f-o-a-m/hs-abci/master/hs-abci-examples/nameservice/images/kibana_discover_filter.png" width="50%"/>
<img src="https://raw.githubusercontent.com/f-o-a-m/kepler/master/hs-abci-docs/nameservice/images/kibana_discover_filter.png" width="50%"/>

(**NOTE**: If you run the e2e tests against the docker network, you should see search results corresponding to the transactions created by the test suite. )

Similarly, you can compose multiple filters to obtain only those logs emitted by the application itself during a *deliverTx* context, i.e. by filtering for `application` on the `ns` namespace field:

<img src="https://raw.githubusercontent.com/f-o-a-m/hs-abci/master/hs-abci-examples/nameservice/images/kibana_discover_filter_advanced.png" width="50%"/>
<img src="https://raw.githubusercontent.com/f-o-a-m/kepler/master/hs-abci-docs/nameservice/images/kibana_discover_filter_advanced.png" width="50%"/>

### Indexing Transaction Events

Expand Down Expand Up @@ -85,5 +85,3 @@ This log corresponds to an event emitted by the `Nameservice` module during tran
```

In this way the log index serves as a rudimentary event indexer for transaction events as well.

## [Next: Metrics](./Metrics.md)
2 changes: 1 addition & 1 deletion hs-abci-docs/doc/99-Metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ title: Metrics

The SDK has some built in support for metrics via [prometheus](https://prometheus.io/), but ultimately you may choose a different runtime interpretation for the metrics, or even choose to ignore it entirely.

The `Nameservice` application uses application specific metrics, for instance increasing the message counters for module level messages, or for timing module responses. It also uses the server metrics via the [metrics middleware](https://github.com/f-o-a-m/hs-abci/blob/master/hs-abci-extra/src/Network/ABCI/Server/Middleware/Metrics.hs) to count ABCI messages and to time server responses. This middleware is highly recommended for any production system.
The `Nameservice` application uses application specific metrics, for instance increasing the message counters for module level messages, or for timing module responses. It also uses the server metrics via the [metrics middleware](https://github.com/f-o-a-m/kepler/blob/master/hs-abci-extra/src/Network/ABCI/Server/Middleware/Metrics.hs) to count ABCI messages and to time server responses. This middleware is highly recommended for any production system.

## Setting up metrics

Expand Down
20 changes: 17 additions & 3 deletions hs-abci-docs/doc/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,20 @@
title: Home
---

The home of Kepler.
Link to [hackage](https://hackage.haskell.org/package/kepler)
Link to [hs-abci-sdk](haddocks/hs-abci-sdk/)
## Introduction

This is the official repository for the Haskell implementation of the ABCI server and SDK for developing applications backed by the Tendermint replication engine.

This site contains a [tutorial](0010-Overview.html) as well as haddocks documentation below.

You can read more about Tendermint and the ABCI specs in the [documentation](https://tendermint.com/docs/spec/abci/) hosted on their website.

## Documentation

- [hs-abci-sdk](haddocks/hs-abci-sdk/)
- [hs-abci-extra](haddocks/hs-abci-extra/)
- [hs-abci-server](haddocks/hs-abci-server/)
- [hs-abci-test-utils](haddocks/hs-abci-test-utils/)
- [hs-abci-types](haddocks/hs-abci-types/)
- [hs-iavl-client](haddocks/hs-iavl-client/)
- [hs-tendermint-client](haddocks/hs-tendermint-client/)
20 changes: 6 additions & 14 deletions hs-abci-docs/nameservice/package.yaml
Original file line number Diff line number Diff line change
@@ -1,20 +1,12 @@
name: nameservice
version: 0.1.0.0
github: "githubuser/nameservice"
license: BSD3
author: "Author name here"
maintainer: "[email protected]"
copyright: "2019 Author name here"
github: "f-o-a-m/kepler/hs-abci-docs/nameservice"
license: Apache
author: "Martin Allen"
maintainer: "[email protected]"
copyright: "2020 Martin Allen"


# Metadata used when publishing your package
# synopsis: Short description of your package
# category: Web

# To avoid duplicated efforts in documentation and dealing with the
# complications of embedding Haddock markup inside cabal files, it is
# common to point users to the README.md file.
description: Please see the README on GitHub at <https://github.com/githubuser/nameservice#readme>
description: Please see the README on GitHub at <https://github.com/f-o-a-m/kepler/blob/master/hs-abci-docs/nameservice/README.md>

extra-source-files:
- README.md
Expand Down
2 changes: 0 additions & 2 deletions hs-abci-docs/nameservice/tutorial/Foundations/02-BaseApp.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,5 +30,3 @@ These effects are:
`BaseApp` acts as an intermediate effect system for specifying applications, it does not make any assumptions about how these effects will be interpreted at runtime. For example, `RawStore` could eventualy be interpeted by any persistent or in-memory storage capable of handling the commands `Put`, `Get` etc.

Most of the work in writing modules involves plugging into `BaseApp` at various points. For example, your module can create custom errors to throw or catch, but you must tell the SDK how to translate this custom error into an `AppError`. Likewise your module can define custom events to log during transaction execution, but you must describe to the SDK how to translate these custom events types into the type `Event`.

[Next: Modules](Modules.md)
2 changes: 0 additions & 2 deletions hs-abci-docs/nameservice/tutorial/Foundations/03-Modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,5 +45,3 @@ data Modules (ms :: [*]) r where
~~~

When you are ready to create your application, you simply specify a value of type `Modules` and some other configuration data, and the SDK will create an `App` for you.

[Next: Types](../Tutorial/Nameservice/Types.md)
Loading

0 comments on commit 9a1c8af

Please sign in to comment.