diff --git a/.gitignore b/.gitignore index 898699d..782bd94 100644 --- a/.gitignore +++ b/.gitignore @@ -108,6 +108,8 @@ target/scala-2.12/tap_2.12-3.0.5.pom target/scala-2.12/twirl/ target/universal/ target/web/ +tap_client/target/* +tap_server/target/* /src/main/scala/tap/nlp/old/ src/main/scala/tap/nlp/old/DocumentConverter.scala src/main/scala/tap/nlp/old/NlpBuilders.scala diff --git a/documentation/developer/doc_updates.md b/documentation/developer/doc_updates.md index 4b92411..d78f4f7 100644 --- a/documentation/developer/doc_updates.md +++ b/documentation/developer/doc_updates.md @@ -1,15 +1,30 @@ -## Documentation Updates +## How to edit documentation -Paradox is used to udpate the project documentation which is maintained under the -src/main/paradox directory. +We use Paradox to automatically build the documentation. -If you update the documentation as part of your work item, you would need to -generate the paradox documentation. +The source files for the documentation is stored under tap/documentation. -Run the following command: +There are 3 folders in the /documentation directory which include the 3 sections that you see on the left. - sbt paradox; sbt copyDocs +``` +documentation/developer +documentation/overview +documentation/user +``` -This will generate html files in the doc directory, and any modified files will be -part of you pull request. +You will notice that within each folder is an `index.md` file which will tell paradox the child pages of that directory. +To set the title of the page at the top of the file include a line like so `#### This is the title` + +The rest of the documentation can be written with simple markdown [Github Style](https://help.github.com/articles/basic-writing-and-formatting-syntax/) + +If you wish to include or change any documentation only edit the files in the documentation folder. The `docs` folder is where paradox will build the final documentation to and should not be edited locally. + +To build your documentation run the following command. + +``` +sbt paradox; sbt copyDocs +``` + +This will generate html files in the docs directory, and any modified files will be +part of you pull request. diff --git a/documentation/developer/ide_setup.md b/documentation/developer/ide_setup.md index f805351..cc79569 100644 --- a/documentation/developer/ide_setup.md +++ b/documentation/developer/ide_setup.md @@ -1,34 +1,43 @@ -## IDE Set-up +# Getting Setup -An IDE provides a more convenient and efficient way of doing development. -The Intellij IDEA is preferred because of its Scala support, and relative ease -of use. +This section will help you get started with the source code on any of the following operating systems. -1. Check that the Scala and SBT plugins are installed. - Install them if they are missing. +First clone the latest version of the Dev branch from [github](https://github.com/infosci-qut/tap/tree/develop) - File-Settings-Plugins +It is recommended that you use an IDE to work on this project as it will provide many helper functions and build tools that make working with sbt and scala and lot easier to manager. -2. Import the project into Intellij IDEA +### Working with Windows(7,10), Mac and Linux (Ubuntu Desktop) with IDEA Ultimate - File - New - Project from Existing sources +The recommended IDE is Intellij IDEA ULTIMATE because of its Scala support, and relative ease +of use. If you have any suggestions for alternate ways of working with this project please let us know by opening an issue. Otherwise the following is a guide to getting setup with IntelliJ IDEA Ultimate. - Navigate to the build.sbt file in the tap directory where you cloned the project source code. +1. When you first open IntelliJ IDEA, We first want to ensure you have the correct plugins. Click configure at the bottom of the start screen and choose Plugins. + Check that you have the 'Scala' and SBT plugins installed. If this is the first time you have run IntelliJ you most likely won't. + +2. Click Browse Repositories at the bottom and type in Scala to search for it then click install plugin. Do the same for the plugin called SBT. +Below is the plugins that you want to install. +![Scala](https://i.imgur.com/pKYUqRh.png) +![SBT](https://i.imgur.com/8jUHUYf.png) + +3. Once you have installed both plugins it will direct you to restart IntelliJ. Once restarted select 'Import Project' and navigate to the directory where you cloned the repo too and choose the build.sbt file. +![demo1](https://i.imgur.com/bk03ddL.png) -3. Ensure the JVM has enough memory to work with (-Xmx2048M -Xss1M -Xmx512M) +4. Make sure Download library sources is ticked and that your Project JDK is chosen. If not you will need to select your JDK, You will need the 1.8 JRE and JDK [found here](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). Then click the New Button > JDK and navigate to your java JRE +In most cases it should be installed to `C:\Program Files\Java\jdk1.8.x` and click ok. +![demo2](https://i.imgur.com/RUToHjc.png) - File - Settings - Other Settings - SBT - VM Parameters +5. Once you click ok IntelliJ may take a while syncing the project(20-40 minutes for first time) Keep an eye on the progress bar at the bottom and wait until it is complete. -4. Add the library dependencies +6. Once it has synced open the app folder and then open the view folder. Right click on HomePage and select 'Run Play 2 App' this will automatically generate your run configuration. It may also download a number of files that SBT needs which may take some time. +Once it has compiled and built you may find it will crash with an Out Of Memory Error. Let's fix that now. - File - Project Structure - Modules +7. Go to the Run Menu at the top and choose 'Edit Configuration', There are a few things we want to change here. + 1. First we want to check that the URL to open is `http://localhost:9000` + 2. Then we want to enter some custom JVM Options `-Xms512M -Xmx6000M -Xss1M -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256M` replacing whatever is already there. + 3. Lastly we want to enter some Environment Variables click the folder icon then the + symbol under 'Name' enter `TAP_HOSTS` and under 'Value' enter `localhost:9000` + 4. Click Apply then ok. + +8. Great now you can right click HomePage again and select 'Run Play 2 App' and it should compile and load up the homepage. - Point to and add the jars you imported into the lib directory: - - cc.factorie.app.nlp.all-models-1.0.0.jar - nlpfactorie_2.12-0.1.jar - -5. Run Tap - - Run - Run Tap +9. You are good to go! Try visiting the graphql interface and see what it can do! diff --git a/documentation/developer/index.md b/documentation/developer/index.md index 0aaf4cf..9af1efe 100644 --- a/documentation/developer/index.md +++ b/documentation/developer/index.md @@ -1,10 +1,10 @@ # Developer @@@ index +* [Getting Setup](ide_setup.md) * [Contributing](contributing.md) -* [Project Sturcture](project_structure.md) -* [IDE Setup](ide_setup.md) -* [Documentation Updates](doc_updates.md) +* [Project Structure](project_structure.md) +* [How to edit documentation](doc_updates.md) @@@ diff --git a/documentation/developer/project_structure.md b/documentation/developer/project_structure.md index 35e494d..5c9dc9b 100644 --- a/documentation/developer/project_structure.md +++ b/documentation/developer/project_structure.md @@ -7,11 +7,39 @@ The build.sbt file indicates that we are using an alternative project structure disablePlugins(PlayLayoutPlugin) PlayKeys.playMonitoredFiles ++= (sourceDirectories in (Compile, TwirlKeys.compileTemplates)).value + +This project is laid out in an MVC structure (Model, View and Controller). + +There are 2 main components to this project, +* The front end (Client) +* The back end (Server) + +The following is a run down of the most relevant files in the project. + +* app - Contains the controllers, models and views. + * controllers - Contains the controllers of the project + * handlers + + * models + * graphql + + * views + * GraphqlPage - The GraphQl Interface page which allows you to test out the graphql queries in a playground. + * HomePage - The home page which contains links to the docs, The source code and the Graphql Interfact. +* documentation - Contains all the documentation source code that can be automatically generated see [Documentation Updates](doc_updates.md) +* tap_client + * src + +* tap_server + * src + + + For more details, see the "Default SBT Layout" section in the "Anatomy of a Play Application" chapter in the Play 2.6 Documentation: - [play-project-anatomy](https://playframework.com/documentation/2.6.x/Anatomy) +[play-project-anatomy](https://playframework.com/documentation/2.6.x/Anatomy) diff --git a/documentation/overview/index.md b/documentation/overview/index.md index 80462de..62025cd 100644 --- a/documentation/overview/index.md +++ b/documentation/overview/index.md @@ -4,7 +4,7 @@ * [Quick Start](quick_start.md) * [Licensing](licensing.md) * [Bugs](bugs.md) -* [Contributing](contributing.md] +* [Contributing](contributing.md) @@@ --- diff --git a/documentation/user/aws_setup.md b/documentation/user/aws_setup.md new file mode 100644 index 0000000..29d2a0e --- /dev/null +++ b/documentation/user/aws_setup.md @@ -0,0 +1,5 @@ +## Get Up and Running with AWS - Coming Soon + +Coming soon. + +If you would like to help with this section see [How to edit documentation](../developer/doc_updates.md) \ No newline at end of file diff --git a/documentation/user/docker_setup.md b/documentation/user/docker_setup.md new file mode 100644 index 0000000..e3269f1 --- /dev/null +++ b/documentation/user/docker_setup.md @@ -0,0 +1,5 @@ +## Get Up and running with Docker - Coming Soon + +Coming soon. + +If you would like to help with this section see [How to edit documentation](../developer/doc_updates.md) \ No newline at end of file diff --git a/documentation/user/index.md b/documentation/user/index.md index c087324..631418f 100644 --- a/documentation/user/index.md +++ b/documentation/user/index.md @@ -1,9 +1,13 @@ ## User @@@ index -* [Product Dependencies](product_dependencies.md) -* [Getting the Source Code](source_code.md) -* [Building TAP](build_product.md) -* [Running TAP](run_product.md) - +* ### Using TAP with the code + * [Product Dependencies](product_dependencies.md) + * [Getting the Source Code](source_code.md) + * [Building TAP](build_product.md) + * [Running TAP](run_product.md) +* ### Using TAP without the code + * [Get Up and Running with AWS - Coming Soon](aws_setup.md) + * [Get Up and running with Docker - Coming Soon](docker_setup.md) + * Using the Tap Python Client - Coming Soon @@@