Skip to content

CodeCharta is a visualization tool that transforms complex software architecture and code metrics into interactive, customizable visual maps, empowering everyone to communicate and analyze your codebase. Improve code quality, maintainability, and architectural decisions

License

Notifications You must be signed in to change notification settings

MaibornWolff/codecharta

Folders and files

NameName
Last commit message
Last commit date

Latest commit

7eea57e Β· Feb 17, 2025
Dec 13, 2024
Dec 5, 2023
Dec 13, 2024
Jan 17, 2025
Dec 13, 2024
Dec 13, 2024
Dec 13, 2024
Feb 13, 2025
Dec 13, 2024
Dec 13, 2024
Dec 13, 2024
Feb 17, 2025
Feb 13, 2025
Dec 13, 2024
Jan 27, 2025
Nov 26, 2024
Dec 13, 2024
Dec 13, 2024
Dec 13, 2024
Dec 13, 2024

Repository files navigation

CodeCharta Docs

The CodeCharta docs use Jekyll and the Minimal Mistakes (MM) Theme. The target of the docs are users (the ones that use the ccsh and the web version) and developers (the ones that maintain and extend CodeCharta). These audiences share similar concerns. As an example most users don't need to know how to write a new importer. They could benefit from the context view, however.

Usage

The generated docs can be viewed locally before being pushed to GitHub (see below). Please note that some files like the web version of CodeCharta are generated by release.yml when the release pipeline runs.

Local

  1. Install Ruby version 2.7.0 or above (check with ruby -v). Please be aware, that some OS come with an old Ruby version. Rubyenv did wonders for me (you can skip these steps if you use rbenv already or have some other way to acquire ruby):
    • brew install rbenv
    • Add eval "$(rbenv init -)" to the ~/.bash_profile, ~/.bashrc, ~/.zshrc etc. dependent on your shell OR execute
      • For Bash: PATH="$HOME/.rbenv/bin:$PATH" and eval "$(rbenv init -)"
      • For Zsh: export PATH="$HOME/.rbenv/bin:$PATH" and eval "$(rbenv init - zsh)"
      • For C-Shell: setenv PATH $HOME/.rbenv/bin:$PATH and eval 'rbenv init - csh'
    • Close terminal
    • Make sure that ~/.rbenv/shims/ruby appears before /usr/bin in the PATH by running echo $PATH
    • which ruby should now point to ~/.rbenv/shims/ruby
    • rbenv install -v 3.0.2
    • OPTIONAL to create a .ruby-version in gh-pages
    • cd gh-pages to go into the docs directory
    • rbenv local 3.0.2
    • ruby -v should now be 3.0.2 for this directory
    • Ensure that the uri module is at version 0.13.0
      • Use irb to open the Ruby shell
      • Run puts URI::VERSION to check the uri version
      • If an upgrade is needed, execute gem install uri
    • bundle to install all gems
      • gem install bundler:2.0.2 and bundle update --bundler in case the bundler needs to be updated first
    • bundle exec jekyll serve to build the site and make it available on a local server
    • Now browse to http://localhost:4000/codecharta/
      • the path /codecharta is there because we added baseurl to our _config.yml

GitHub

GitHub uses Jekyll to render static site content for Github-Pages. Content in a top-level docs folder or in a branch gh-pages is automatically rendered.

GitHub does not support all Jekyll plugins however and only supports those it has whitelisted.

Modify the docs

In case it's important the technical underpinnings of Jekyll and Minimal Mistakes are described in the Tech Chapter.

Draw.io

The assets/img/*.drawio.* files can be opened directly with Draw.io. Download Draw.io, click on File->Open and select the image file. Yes you can open an image file directly. This is because we exported the image with a complete copy of the diagram in the meta-data: File->Export As->PNG then "Include copy of my diagram".

Tech

Jekyll is a static site renderer written in Ruby and most notably it is directly supported by GitHub. By default, it does not provide any look-and-feel for your sites. MM provides that theme (css, layouts, some js etc.) and also adds very nice things like search.

At first sight Jekyll is very simple. Basically "all" it does is copy files from your project structure to the generated folder called _site. So if you place an index.html in your project root, it'll also be in the root of _site. What creates value is that Jekyll can also modify the files during the copy operation, provided we tell it to:

The Front Matter Header in a html file:

---
title: Some Title
customVariable: Dave
---

<p>Hi {{customVariable}}</p>

In all cases the file is processed using the Liquid Template Engine which we can use to replace parts of the file with any variable that is available. Some variables like {{date}} are predefined by Jekyll. But we can also define our own custom variables like {{customVariable}} in the Front Matter Header or in the _config.yml.

Configuration

Besides defining global variables, the _config.yml is also used to configure Jekyll and the MM Theme. It also contains some comments that explain what the variables do. To further understand what the variables do it's best to check out the Jekyll Configuration and the MM Configuration. Please note that changes to the _config.yml won't be picked up by bundle exec jekyll serve. You need to stop and restart that command.

Modifying the Template

MM can be modified by copying files from MM directly and changing their content. Take a look at the files in _includes.

Markdown

Jekyll uses kramdown to parse Markdown. Please take a look at its qickref. Also, please use this format for internal links between markdown files: [visualization]({{site.docs_visualization}}/visualization). It has the benefit that the build will fail locally if a file cannot be found. A link to a section of a different page would look like this: [link text]({{site.baseurl}}{% link _docs/01-01-document.md %}#section).

Troubleshoot Docs Generation

Port Occupied

  • netstat -vanp tcp | grep 4000
  • kill <pid>

Initial Project Creation

  • mkdir -p <project>/docs
  • cd <project>
  • rbenv local 2.6.3
  • cd docs
  • jekyll new .
  • Read Minimal Mistakes Quickstart
  • Set the remote theme: remote_theme: "mmistakes/minimal-mistakes"
  • ???
  • Profit