From a55c4151c77f1b28d31c2584fe38f3a3cb44d56b Mon Sep 17 00:00:00 2001 From: Remi Laplace Date: Thu, 28 Feb 2019 14:05:09 +0100 Subject: [PATCH] Chg: improving docs --- CHANGELOG.md | 2 +- README.md | 21 +-- apps/examples/CreateUserProject.md | 215 +++++++++++++++++++++++++++++ fats/README.md | 4 +- 4 files changed, 230 insertions(+), 12 deletions(-) create mode 100644 apps/examples/CreateUserProject.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e74c218b..7013cc1f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ As of version 1.0.0, the project will try and follow [Semantic Versioning](https * empty -## [1.0.0] - 2019/0X/XX +## [1.0.0] - 2019/02/28 This first official version introduces several changes. They are listed here. diff --git a/README.md b/README.md index 1f8cfbcc..91e09190 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -[![Build Status](https://travis-ci.org/jbotsim/JBotSim.svg?branch=master)][github-jbotsim] -[![Maven Central](https://img.shields.io/badge/maven%20central-1.0.0-red.svg)](https://search.maven.org/search?q=g:io.jbotsim%20AND%20v:1.0.0) -[![License](https://img.shields.io/badge/license-LGPL%20≥%203.0-blue.svg)][lgpl3] +[![Build Status](https://travis-ci.org/jbotsim/JBotSim.svg?branch=master)][travis-jbotsim] +[![Maven Central](https://img.shields.io/badge/maven%20central-1.0.0-informational.svg)][mavencentral-jbotsim-1-0-0] +[![License](https://img.shields.io/badge/license-LGPL%20≥%203.0-informational.svg)][lgpl3] @@ -9,7 +9,7 @@ * [Introduction](#introduction) * [Hello World example](#hello-world-example) - * [Current Version](#current-version) + * [Current version](#current-version) * [*Maven* dependency](#maven-dependency) + [Using Gradle](#using-gradle) + [Using Maven](#using-maven) @@ -42,7 +42,7 @@ It is that simple! ### Declaring the dependency > Here, we work with a IntelliJ IDEA Java project, fetching dependencies from Maven Central. -> For other project configurations, see TODO. +> Other configurations are detailed [here](apps/examples/CreateUserProject.md). For this HelloWorld, we will simply retrieve the `jbotsim-all` artifact @@ -95,12 +95,12 @@ the user by selecting *"Start execution"* in the `JViewer`'s contextual menu (ri > Please see the [*Examples*](http://jbotsim.io/?p=examples) section of [JBotSim's website](http://jbotsim.io) for more examples. -## Current Version +## Current version > Note: As of version `1.0.0`, the JBotSim project will try and follow the rules provided by the [Semantic Versioning](https://semver.org/). -The latest public version is [`1.0-beta03`](https://sourceforge.net/projects/jbotsim/files/latest/download). +The latest public version is [`1.0.0`][mavencentral-jbotsim-1-0-0]. Please see the [CHANGELOG.md](CHANGELOG.md) for previous versions modifications. @@ -150,7 +150,7 @@ If your build system uses *Maven*, you will want to add something like this to y If you use a _Java Project_ in _IntelliJ IDEA_, add the following dependency (as explained [here](#declaring-the-dependency)): ``` - "io.jbotsim:jbotsim-all:1.0.0" + io.jbotsim:jbotsim-all:1.0.0 ``` @@ -160,7 +160,7 @@ The JBotSim project is separated in three main modules. Please follow the links to each of them for more information: * [`apps`](./apps/README.md): contains some sample apps and mains using modules from `lib`. * [`lib`](./lib/README.md): contains submodules responsible for the generation and publication of unitary *jars* files -on [Maven Central](https://search.maven.org/search?q=g:io.jbotsim). +on [Maven Central][mavencentral-jbotsim]. * [`fats`](./fats/README.md): contains submodules responsible for the generation of standalone *fat jars* by using existing published JBotSim jars (published by `lib`). @@ -206,6 +206,9 @@ gpg --keyserver hkp://pool.sks-keyservers.net --recv-keys DFA48EDB1EDEBA6F ``` +[travis-jbotsim]: https://travis-ci.org/jbotsim/JBotSim [github-jbotsim]: https://github.com/jbotsim/JBotSim +[mavencentral-jbotsim-1-0-0]: https://search.maven.org/search?q=g:io.jbotsim%20AND%20v:1.0.0 +[mavencentral-jbotsim]: https://search.maven.org/search?q=g:io.jbotsim [github-jbotsim-issues]: https://github.com/jbotsim/JBotSim/issues [lgpl3]: http://www.gnu.org/licenses/lgpl-3.0.html diff --git a/apps/examples/CreateUserProject.md b/apps/examples/CreateUserProject.md new file mode 100644 index 00000000..f9727c6f --- /dev/null +++ b/apps/examples/CreateUserProject.md @@ -0,0 +1,215 @@ + +# Creating a project using JBotSim +> The steps described here have been generated with a IntelliJ IDEA 2018.3.3 (Ultimate Edition) +> (Build #IU-183.5153.38, built on January 9, 2019) + + +## Pre requisite +The guidance provided here suppose that you have a +[usable](https://www.jetbrains.com/help/idea/install-and-set-up-product.html) *IntelliJ IDEA* instance. + +## Introduction + +In this documentation, we focus on creating a project that will: +* allow you to run JBotSim's [*Hello World*](./README.md#helloworld-class), +* make *IntelliJ IDEA*'s [Quick Documentation](https://www.jetbrains.com/help/idea/viewing-reference-information.html#inline-quick-documentation) +on JBotSim symbols available. + + + +The configuration process takes place in the following two steps. +* First, the [project creation](#project-creation). You will either be: + * [creating a Java project](#creating-a-java-project) or + * [creating a Gradle project](#creating-a-gradle-project). +* Then, the [configuration of your dependency to JBotSim](#adding-the-jbotsim-dependency): + * using the [Maven central version](#using-the-maven-central-version) with + * a [Java project](#java-project) or + * a [Gradle project](#gradle-project); + * using the [standalone jar version](#using-the-standalone-jar-version) with + * a [Java project](#java-project-standalone) or + * a [Gradle project](#gradle-project-standalone). + +## Project creation + +### Creating a Java project + +* Starting the new project wizard: + + `File` > `New` > `Project...` + +* Creating a Java project + + * Select: `Java` + * Make sure a *Project SDK* is selected (either 8 or 10) -- should be set by default + * Nothing more to select. You can deselect anything selected in there. + * Hit `Next`. + +* Choosing a template + + * You can optionally select the `Java Hello World` template. + + This will generate a `Main.java` file. + * Hit `Next`. + +* Choosing your project's name and directory + + * Provide a project name + * Provide a directory + + This field is automatically filled by *IntelliJ IDEA* depending on your project's name. In most cases, you will want + to leave it as is. + * Hit `Finish`. + + After some automatic configuration, the project should be created. + +### Creating a Gradle project + +* Starting the new project wizard: + + `File` > `New` > `Project...` + +* Creating a Java project + + * Select: `Gradle` + * Make sure a Project SDK is chosen (either 8 or 10) -- should be set by default + * In "Additional Libraries and Frameworks", make sure "Java" is ticked. + * Hit `Next`. + +* *GroupId* and *ArtifactId* Screen + * Fill in the fields: + * `GroupId`: your namespace (*e.g.* `com.example`) + * `ArtifactId`: your application/library name (*e.g.* `jbotsim-app`) + * `Version`: leave as is (usually `1.0-SNAPSHOT`) + * Hit `Next`. + +* Gradle configuration screen + * tick `Use auto-import` + * make sure `Use default gradle wrapper` radio button is selected + * you can leave the rest as is + * Hit `Next`. + + +* Project name and location screen + * these should already be filled in. Only modify those fields if you know you have to. + * Hit `Finish`. + + After some automatic configuration, the project should be created. + + +## Adding the JBotSim dependency + +### Using the Maven Central version + +This method takes advantage of the fact that JBotSim has been published on *Maven Central*. + + +Any JBotSim classes, source code and documentation will automatically be downloaded for you. + +#### Java project + +***Adding the JBotSim project jar as a dependency*** + * Open the Project Structure popup + + `File` > `Project Structure` + + * Open the "New Project Library" popup: + * select `Libraries` in the left panel + * click `+` + * choose `From Maven ...`. + + * In the "Download Library from Maven Repository" popup: + * provide the following dependency: `io.jbotsim:jbotsim-all:1.0.0` + * make sure to tick `JavaDocs` + * Hit `OK`. + * Confirm that you want to add it to your (only) module. + + And you are done! You can copy paste the example. + +***Documentation*** +* if you have ticked "JavaDocs", the documentation should already be available. +* you can also provide the *javadoc-only* *jar*, containing only the javadoc, by using the same process described +[here](#java-project-standalone). +* providing the url to the online javadoc is still possible + * open Project Structure + * in `Libraries`, select your maven dependency + * click on `Specify Documentation URL` + * provide the javadoc url + +#### Gradle project + +Simply add the following line to your `build.gradle`: + +``` +dependencies { + implementation "io.jbotsim:jbotsim-all:1.0.0" +} +``` + + +### Using the standalone jar version + +> Using the standalone version should be reserved to already existing projects and offline usages. +> Please consider using the [Maven Central version](#using-the-maven-central-version). + + +#### Java project standalone + +***Adding the JBotSim project jar as a dependency*** + * Open the Project Structure popup + + `File` > `Project Structure` + + * Open the "New Project Library" popup: + * select `Libraries` in the left panel + * click `+` + * choose `Java`. + + * In the popup, provide the JBotSim full *jar* (from the location you stored it) + * Confirm that you want to add it to your (only) module. + + And you are done! You can copy paste the example. + +***Documentation*** +* if you have provided the *classes + javadoc* jar, intellij will automatically find the documentation. + + Be careful on not distributing your application with this version of the *jar*. + +* if you have provided the *classes only* jar, can add documentation by: + * providing the *javadoc-only* *jar*, containing only the javadoc, by using the same process. + + * providing the url to the online javadoc + * open Project Structure + * select your .jar in modules + * click on `Specify Documentation URL` + * provide the javadoc url + + +#### Gradle project standalone + +>Creating a *gradle* project with the fat-jar makes sense if you are really afraid of (or not able to use) *maven* at +>the time you create your project but consider using it later. + +>Please see [gradle-related *maven* configuration](#gradle-project). + + +***Adding the JBotSim project jar as a dependency*** + * Put the jar in a directory inside your project + + *e.g.* directory `mylibs` + + * In the `build.gradle` file, add the following statement: + + ``` + dependencies { + compile files('mylibs/jbotsim-full-1.0.0.jar') + } + ``` + + And you are done! You can copy paste the example. + + +***Documentation*** +* you can also provide the *javadoc-only* *jar*, containing only the javadoc, by using the same process described +[here](#java-project-standalone). +* providing the url to the online javadoc can work, but should be linked to another (possibly empty) lib, or your jvm. + diff --git a/fats/README.md b/fats/README.md index ac50ff0d..a9a596f8 100644 --- a/fats/README.md +++ b/fats/README.md @@ -19,6 +19,6 @@ See [project structure](#project-structure) for existing ones. ## Project structure The submodules are listed below: -* [`jbotsim-full`](./jbotsim-full/README.md): a *fat jar* containing all JBotSim *jars*. -* [`jbotsim-common`](./jbotsim-common/README.md): a *fat jar* containing all non-specific classes from JBotSim. +* [`fat-jbotsim-full`](./fat-jbotsim-full/README.md): a *fat jar* containing all JBotSim *jars*. +* [`fat-jbotsim-common`](./fat-jbotsim-common/README.md): a *fat jar* containing all non-specific classes from JBotSim.