diff --git a/CHANGELOG.md b/CHANGELOG.md index baeb0f4952..0646c088d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/) - Add metric tooltips that display attribute descriptors and provide hyperlinks in the sidebar to the metric's documentation [#3273](https://github.com/MaibornWolff/codecharta/pull/3273)
+- Expand and restructure documentation regarding Docker usage [#3312](https://github.com/MaibornWolff/codecharta/pull/3312) ### Fixed 🐞 @@ -20,9 +21,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/) ### Added 🚀 -- Added support for parser suggestions to SVN-, MetricGardener-, RawText- and SourceCodeParser [#3287](https://github.com/MaibornWolff/codecharta/pull/3287)
+- Add support for parser suggestions to SVN-, MetricGardener-, RawText- and SourceCodeParser [#3287](https://github.com/MaibornWolff/codecharta/pull/3287) - Add semi automatic merging feature after executing multiple parsers [#3287](https://github.com/MaibornWolff/codecharta/pull/3287) -- Expanded developer documentation to include common problems and solutions for them [#3289](https://github.com/MaibornWolff/codecharta/pull/3289) +- Expand developer documentation to include common problems and solutions for them [#3289](https://github.com/MaibornWolff/codecharta/pull/3289) ### Fixed 🐞 diff --git a/analysis/README.md b/analysis/README.md index a47ca42d44..fb7931eb05 100644 --- a/analysis/README.md +++ b/analysis/README.md @@ -53,6 +53,15 @@ Components that export data from visualisation data to other formats. - Bash or similar - JRE 8-11 (Oracle Java or OpenJDK) +# Installation + +You can start with **Codecharta Analysis** on multiple ways: + +- Installation as a [npm package](#installation-via-npm) (Recommended) +- Use our [Docker Image](#installation-via-docker) to run the analysis in a container +- Use [docker-compose](https://maibornwolff.github.io/codecharta/docs/docker-containers/) to run the analysis in a complete environment with other needed tools like Sonar and a running CodeCharta Visualization instance to view your city map. +- Download the SourceCode and [build it yourself](#manual-installation) + ## Installation via npm This installs all binaries to run the analysis. Java 11 is recommended, while Java 8 is still supported. @@ -61,7 +70,21 @@ This installs all binaries to run the analysis. Java 11 is recommended, while Ja To run it you can call `ccsh` -## Installation +## Installation via Docker + +You can use Codecharta analysis in multiple ways. This section will deal with how to use the analysis as a standalone container. For information on how to use with docker compose, please check out our [docker compose documentation](https://maibornwolff.github.io/codecharta/docs/docker-containers/). +We assume that you already installed docker, if not, you have to do that before! + +To containerize the analysis, please follow the below listed steps. + +- Navigate into the directory you want to analyse with CodeCharta. There are multiple ways to use the docker image: + 1. Start the docker container and a bash shell in it with `docker run --name codecharta-analysis -it -v $(pwd):$(pwd) -w $(pwd) codecharta/codecharta-analysis bash`. This runs the image, names the container `codecharta-analysis`, mounts the current directory and sets it as the working directory of your container. You can now use the codecharta shell or any other of the tools installed in the container via the command line. + 2. Start the docker container and directly use some command (like the ccsh): `docker run --name codecharta-analysis -it -v $(pwd):$(pwd) -w $(pwd) codecharta/codecharta-analysis ccsh`. This starts the Ccsh without any commands, which will open an interactive codecharta shell that will guide you through the parsing/analyzing process. The working directory of your Terminal will be used as the working directory of the container. + 3. Start the docker container and directly use a specific parser: `docker run --name codecharta-analysis -it -v $(pwd):$(pwd) -w $(pwd) codecharta/codecharta-analysis ccsh rawtextparser .`. This starts the RawTextParser in the current working directory in a container. +- After executing the run command once, you can repeat the same docker configuration with `docker start codecharta-analysis` or you have to change the name or delete the old container if you want to `docker run` a different configuration. +- After analysing, you can copy any results with `docker cp codecharta-analysis:/your/path/fileName.cc.json fileName.cc.json` to your current working directory (replace `/your/path/` with correct path in container). If this does not work, make sure you assigned the name `codecharta-analysis` to your container, if not use the correct name or container id. + +## Manual Installation - Download / build package - Unzip / untar package in desired destination folder (named CC_INSTALL_DIR) @@ -72,6 +95,8 @@ To run it you can call `ccsh` - Enter `ccsh` and press `TAB` to see available commands - Enter `ccsh -` and press `TAB` to see available parameters +# Other + ## Build Via gradle: diff --git a/gh-pages/_data/navigation.yml b/gh-pages/_data/navigation.yml index 8ad1b4ff44..0ff21d4938 100644 --- a/gh-pages/_data/navigation.yml +++ b/gh-pages/_data/navigation.yml @@ -15,6 +15,8 @@ docs: url: /docs/quick-start-guide/ - title: "Installation" url: /docs/installation/ + - title: "Docker Containers" + url: /docs/docker-containers/ - title: "Versioning" url: /docs/versioning/ - title: "Price" @@ -38,8 +40,6 @@ docs: url: /docs/custom-metrics/ - title: "Analyze with SonarQube" url: /docs/analyze-with-sonarqube/ - - title: "Docker Containers" - url: /docs/docker-containers/ - title: Analysing-Tools children: diff --git a/gh-pages/_docs/05-06-docker-containers.md b/gh-pages/_docs/01-04-docker-containers.md similarity index 100% rename from gh-pages/_docs/05-06-docker-containers.md rename to gh-pages/_docs/01-04-docker-containers.md diff --git a/gh-pages/_docs/07-01-new-to-code.md b/gh-pages/_docs/07-01-new-to-code.md index 2d4c941fb3..6aa8c1f893 100644 --- a/gh-pages/_docs/07-01-new-to-code.md +++ b/gh-pages/_docs/07-01-new-to-code.md @@ -14,8 +14,8 @@ When updating your branch, we prefer using a rebase instead of merging to keep t # Code Style Guide -Besides the rules enforced by our linter, we do not follow a set of defined style guidelines for our code. -Just try to make your code readable and follow common best practices. +Besides the rules enforced by our linter, we generally do not follow a set of defined style guidelines for our code. +For the analysis there is an XML file containing a few style rules for your IDE, you can find out more about that in the analysis readme. # GitHub Actions diff --git a/visualization/README.md b/visualization/README.md index ae76859920..640664db2a 100755 --- a/visualization/README.md +++ b/visualization/README.md @@ -1,6 +1,6 @@ # CodeCharta Visualization -[![Build Status](https://travis-ci.org/MaibornWolff/codecharta.svg?branch=main)](https://travis-ci.org/MaibornWolff/codecharta) +[![Quality Gate Status For Visualization](https://sonarcloud.io/api/project_badges/measure?project=maibornwolff-gmbh_codecharta_visualization&metric=alert_status)](https://sonarcloud.io/project/overview?id=maibornwolff-gmbh_codecharta_visualization) > CodeCharta by [MaibornWolff](https://www.maibornwolff.de) @@ -19,6 +19,8 @@ You can start with **Codecharta Visualization** on multiple ways: - Installation as a [npm package](#npm-package) (Recommended) - Run an operating system specific [standalone](#run-a-standalone) - Build it yourself from the github [repository](#build-it-yourself) +- Use [docker-compose](https://maibornwolff.github.io/codecharta/docs/docker-containers/) to run this with other needed tools like a Sonar instance or analyzing tools of codecharta-analysis. +- Use our [Dockerfile](#run-in-docker-container) to run the visualization in a container - Try out the [online version](https://maibornwolff.github.io/codecharta/visualization/app/index.html?file=codecharta.cc.json&file=codecharta_analysis.cc.json) > Be aware, that if you are on Apple Silicon, you need to do additional config for npm installation @@ -140,6 +142,16 @@ $ npm run e2e:auto > To follow/watch the steps the e2e test is performing, deactivate headless mode in `jest-puppeteer.config.js` (and maybe set the `slowMo` parameter) +## Run in Docker container + +You can use this via docker compose or as a standalone container. This section will deal with how to use the visualization as a standalone container. For information on how to use this with docker compose, please check out [Docker Getting Started](https://maibornwolff.github.io/codecharta/docs/docker-containers/) +We assume that you already installed docker, if not, you have to do that before! + +To containerize the visualization, please follow the below listed steps. + +- Start the docker container: `docker run -d -p 9000:80 codecharta/codecharta-visualization`. This detaches the container and exposes port 80 on the container and port 9000 on the host. +- Open `localhost:9000` in your browser and you can already use the visualization, upload `cc.json` files and play around! + # JSON structure [Example Data](/visualization/app/codeCharta/assets/sample1.cc.json)