Skip to content

Commit

Permalink
NCL-5975 Move documentation to gh-pages and add more documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@rnc
rnc committed Oct 27, 2020
1 parent 3797985 commit ff74556
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 149 deletions.
40 changes: 37 additions & 3 deletions DEVELOPING.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,38 @@

# Developers Guide
# Table of Contents

## Adding JSON Output
<!-- TocDown Begin -->
* [Prerequisites](#prerequisites)
* [Coding](#coding)
* [Exception Handling](#exception-handling)
* [Adding JSON Output](#adding-json-output)
* [Adding Example Usage Messages](#adding-example-usage-messages)
* [Documentation](#documentation)
<!-- TocDown End -->

## Prerequisites

* Java 1.8 or later
* Maven 3.3.9 or later

## Coding

### Exception Handling

`FatalException` support SLF4J style `{}` substitution parameters. For example

throw new FatalException( "Unable to detect charset for file {}", jsonFile, exceptionObject );
throw new FatalException( "Internal failure ; replaced {} by {}", old, d );
throw new FatalException( "Unable to parse", exceptionObject );

### Adding JSON Output

The JSON option (`-o`) is defined as an inherited option in the top level App. In order for implementations to retrieve its value they should extend `JSONCommandHandler` which provides a function to return the value:
```
protected boolean getJsonOutput()
```

## Adding Example Usage Messages
### Adding Example Usage Messages

Sometimes it is useful to be able to add an example of how to use a command on top of the basic usage message. This may be
accomplished by using the `footer` attribute combined with a predefined constant e.g.
Expand All @@ -28,3 +52,13 @@ Get an artifact by its id
Example:
$ bacon pnc artifact get 10
```

## Documentation

In order to edit the website at https://project-ncl.github.io/bacon checkout the `gh-pages` branch.
It is possible to use Jekyll (https://help.github.com/articles/using-jekyll-with-pages) to preview the changes.
Jekyll can be run with `jekyll serve --watch -V` and may be installed in Fedora via the `rubygem-jekyll` package.

This README's table of contents is generated by [tocdown](https://github.com/dohliam/tocdown) using the following command line:
ruby .../tocdown/toc.rb -b -r -t -d 3 -s -m <markdown-file>
154 changes: 8 additions & 146 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,154 +1,16 @@
# Bacon
Bacon is a new Java CLI for PNC 2.0 combining features of old PNC, DA CLI and PiG tooling.

## Documentation
The [Developer's guide](https://github.com/project-ncl/bacon/blob/master/DEVELOPING.md) is a good start on how to get up and running with developing in Bacon.
# Introduction

The [PiG `build-config.yaml` guide](https://github.com/project-ncl/bacon/wiki/Anatomy-of-a-build-config.yaml) provides information on how to build your own `build-config.yaml` file for PiG.
Bacon is a new Java CLI for [ProjectNCL](https://github.com/project-ncl/pnc) 2.0 combining features of old PNC, DA CLI and PiG tooling.

Finally, our [changelog](https://github.com/project-ncl/bacon/wiki/Changelog) lists the changes that happened in releases.
# Documentation

---
# Reporting an issue
To report an issue, please use the internal JIRA instance. The Github issues usage is now disabled.

# Common Usages
Compile:
```bash
mvn clean install
```

Run:
```bash
java -jar cli/target/bacon.jar
```

To install the latest ***released*** version:
```bash
curl -fsSL https://raw.github.com/project-ncl/bacon/master/bacon_install.py | python3 -
```

To install a specific ***released*** version:
```bash
curl -fsSL https://raw.github.com/project-ncl/bacon/master/bacon_install.py | python3 - 2.0.1
```

To install the latest ***snapshot*** (no need to compile):
```bash
curl -fsSL https://raw.github.com/project-ncl/bacon/master/bacon_install.py | python3 - snapshot
```

This will install the `bacon`, `pig`, `da` and `pnc` commands in the `~/bin`
directory, which on Linux will make it available in your shell.

To update the installed version:
```bash
# latest released version
bacon update

# specifc released version
bacon update 2.0.1

# snapshot version
bacon update snapshot
```
User documentation is available [here](https://project-ncl.github.io/bacon). This includes guidance on the `build-config.yaml` files and the features available.

# Configuration
Contributions are welcome! Please see the [Developer's guide](https://github.com/project-ncl/bacon/blob/master/DEVELOPING.md) to get up and running with developing in Bacon.

An example configuration is present here: https://github.com/project-ncl/bacon/blob/master/config.yaml

The default configuration used by `bacon` should be located in folder: `~/.config/pnc-bacon/` with name `config.yaml`. We can specify a different folder for the location of the `config.yaml` via the `-p` flag:

```bash
bacon pnc build cancel -p <alternate folder containing config.yaml> 1000
```

We can specify several profiles in the configuration file. This is useful when dealing with different PNC servers and/or configurations. We can use the `--profile` flag to choose the non-default one:

```bash
bacon pnc build cancel --profile coolProfile 1000
```

## Authentication

To authenticate to PNC Authentication servers, add this to your `config.yaml`:

```yaml
keycloak:
url: "http://keycloak.com"
realm: ""
username: ""

# if regular user
clientId: ""
password: ""

# if service account
# clientSecret: ""
```
Finally, our [changelog](https://project-ncl.github.io/bacon/changelog.html) lists the changes that happened in releases.

---

# PiG
PiG allows users to setup PNC with the product, build configurations, and much more via a YAML file. This makes it much easier to configure PNC for new releases as well as making the configuration portable across different PNC servers.

PiG is run in multiple phases:

- configure
- build
- repo
- licenses
- javadocs
- sources
- shared-content
- docs
- scripts
- addons

The all-in-one phase that combines all the phases is:

- run

The `configure` phase pushes all the settings in the YAML file to PNC, and the `build` phase tells PNC to build everything.

```bash
bacon pig <phase> ...
```
## Configuration

The application is configured via the `build-config.yaml` file.

A PiG `build-config.yaml` looks like [this](https://github.com/project-ncl/bacon/blob/master/example-pig-config.yaml). See [this](https://github.com/project-ncl/bacon/wiki/Anatomy-of-a-build-config.yaml) detailed guide of `build-config.yaml`

TODO: add a command that allows users to specify variables via cli

## configure

Usage:
```bash
bacon pig configure <directrory containing build-config.yaml>
```

## build

Usage:
```bash
bacon pig configure <directrory containing build-config.yaml>
```

You can specify if you want temporary builds or not with the `-t` flag.

## Deliverables

This section covers the required deliverables for a product release:

- licenses
- maven-repository
- src zip
- javadoc zip

TODO: describe each section more

## Add ons

TODO: Description of add-ons
# Reporting an issue
To report an issue, please use the NCLSUP/NCL projects in the internal JIRA instance. The Github issues usage is now disabled.

0 comments on commit ff74556

Please sign in to comment.