Skip to content

Commit

Permalink
[#1996] Update frontend documentation (#1999)
Browse files Browse the repository at this point in the history 
The HTML report documentation is outdated after changes introduced in
recent PRs. This will make it difficult for new contributors to
understand the frontend codebase.

Let us update the documentation and puml diagrams to match the new files
and architecture. Let us also comment out the links used as examples to
avoid broken links.
  • Loading branch information
@ckcherry23
ckcherry23 authored May 5, 2023
1 parent 1cc3e67 commit 50dd4ab
Show file tree
Hide file tree
Showing 6 changed files with 61 additions and 55 deletions.
45 changes: 23 additions & 22 deletions docs/dg/report.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,10 @@ The following is a snapshot of the report:

## Report architecture

<!-- Use image instead of puml diagram for this as auto-render may not work -->
![report architecture](../images/report-architecture.png)

The main Vue object (`app.vue`) is responsible for loading the report via an async call to `api.js`, which parses `summary.json`. Its `repos` attribute is tied to the global `window.REPOS`, and is passed into the various other modules when the information is needed.
The main Vue object (`app.vue`) is responsible for loading the report via an async call to `api.ts`, which parses `summary.json`. Its `repos` attribute is tied to the global `window.REPOS`, and is passed into the various other modules when the information is needed.

The report interface is broken down into two main parts
- the summary view
Expand All @@ -31,18 +32,18 @@ The tabbed interface is responsible for loading various modules such as authorsh

<!-- ==================================================================================================== -->

## Javascript and Vue files
## Typescript and Vue files

- **main.js** - sets up plugins and 3rd party components used in the report
- **main.ts** - sets up plugins and 3rd party components used in the report
- [**app.vue**](#app-app-vue) - module that renders the `router-view`
- [**api.js**](#data-loader-api-js) - loading and parsing of the report content
- [**c_home.vue**](#home-view-c-home-vue) - module that supports the report interface
- [**c_widget.vue**](#widget-view-c-widget-vue) - module that supports the widget interface
- [**c_summary.vue**](#summary-view-c-summary-vue) - module that supports the summary view
- [**c_authorship.vue**](#authorship-view-c-authorship-vue) - module that supports the authorship tab view
- [**c_zoom.vue**](#zoom-view-c-zoom-vue) - module that supports the zoom tab view
- [**c_ramp.vue**](#ramp-view-c-ramp-vue) - module that supports the ramp chart view
- [**c_segment.vue**](#segment-view-c-segment-vue) - module that supports the code segment view
- [**api.ts**](#data-loader-api-ts) - loading and parsing of the report content
- [**c-home.vue**](#home-view-c-home-vue) - module that supports the report interface
- [**c-widget.vue**](#widget-view-c-widget-vue) - module that supports the widget interface
- [**c-summary.vue**](#summary-view-c-summary-vue) - module that supports the summary view
- [**c-authorship.vue**](#authorship-view-c-authorship-vue) - module that supports the authorship tab view
- [**c-zoom.vue**](#zoom-view-c-zoom-vue) - module that supports the zoom tab view
- [**c-ramp.vue**](#ramp-view-c-ramp-vue) - module that supports the ramp chart view
- [**c-segment.vue**](#segment-view-c-segment-vue) - module that supports the code segment view

<!-- ==================================================================================================== -->

Expand All @@ -58,22 +59,22 @@ The tabbed interface is responsible for loading various modules such as authorsh

This contains the logic for the main VueJS object, `app.vue`, which is the entry point for the web application.

Vuex in `store.js` is used to pass the necessary data into the relevant modules.
Vuex in `store.ts` is used to pass the necessary data into the relevant modules.

`c_home`, `c_widget`, `c_summary`, `c_authorship`, `c_zoom`, `c_segment`, and `c_ramp` are components embedded into the report and will render the corresponding content based on the data passed into it from Vuex.
`c-home`, `c-widget`, `c-summary`, `c-authorship`, `c-zoom`, `c-segment`, and `c-ramp` are components embedded into the report and will render the corresponding content based on the data passed into it from Vuex.

### Loading of report information
The main Vue object depends on the `summary.json` data to determine the right `commits.json` files to load into memory. This is handled by `api.js`, which loads the relevant file information from the network files if available; otherwise, a report archive, `archive.zip`, has to be used.
The main Vue object depends on the `summary.json` data to determine the right `commits.json` files to load into memory. This is handled by `api.ts`, which loads the relevant file information from the network files if available; otherwise, a report archive, `archive.zip`, has to be used.

Once the relevant `commit.json` files are loaded, all the repo information will be passed into `c_summary` to be loaded in the summary view as the relevant ramp charts.
Once the relevant `commit.json` files are loaded, all the repo information will be passed into `c-summary` to be loaded in the summary view as the relevant ramp charts.

### Activating additional view modules
Most activity or actions should happen within the module itself, but in the case where there is a need to spawn or alter the view of another module, an event is emitted from the first module to the Vuex store, which then handles the data received and passes it along to the relevant modules.

### Hash link
Other than the global main Vue object, another global variable we have is the `window.hashParams`. This object is responsible for generating the relevant permalink for a specific view of the report's summary module.

## Data loader ([api.js](https://github.com/reposense/RepoSense/blob/master/frontend/src/utils/api.js))
## Data loader ([api.ts](https://github.com/reposense/RepoSense/blob/master/frontend/src/utils/api.ts))
This is the module that is in charge of loading and parsing the data files generated as part of the report.

### Loading from ZIP file
Expand All @@ -92,21 +93,21 @@ For the basic skeleton of `window.REPOS`, refer to the generated `summary.json`

## Home view ([c-home.vue](https://github.com/reposense/RepoSense/blob/master/frontend/src/views/c-home.vue))

The `c_home` module is in charge of rendering the main report, and renders `c_resizer`, `c_summary`, `c_authorship` and `c_zoom`.
The `c-home` module is in charge of rendering the main report, and renders `c-resizer`, `c-summary`, `c-authorship` and `c-zoom`.

<!-- ==================================================================================================== -->

## Widget view ([c-widget.vue](https://github.com/reposense/RepoSense/blob/master/frontend/src/views/c-widget.vue))

The `c_widget` module is in charge of rendering the widget from the `iframe` and only renders `c_summary`. An additional prop, `isWidgetMode`, is passed to `c_summary` so it knows to render as a widget and omit unnecessary elements.
The `c-widget` module is in charge of rendering the widget from the `iframe` and only renders `c-summary`. An additional prop, `isWidgetMode`, is passed to `c-summary` so it knows to render as a widget and omit unnecessary elements.



<!-- ==================================================================================================== -->

## Summary view ([c-summary.vue](https://github.com/reposense/RepoSense/blob/master/frontend/src/views/c-summary.vue))

The `c_summary` module is in charge of loading the ramp charts from the corresponding `commits.json`.
The `c-summary` module is in charge of loading the ramp charts from the corresponding `commits.json`.

<puml src="../diagrams/ReportArchitectureSummary.puml"/>

Expand All @@ -131,13 +132,13 @@ The files will be filtered, picking only files the selected author has written i

## Zoom view ([c-zoom.vue](https://github.com/reposense/RepoSense/blob/master/frontend/src/views/c-zoom.vue))

The `c_zoom` module is in charge of filtering and displaying the commits from the ramp chart's selected sub-range.
The `c-zoom` module is in charge of filtering and displaying the commits from the ramp chart's selected sub-range.

<!-- ==================================================================================================== -->

## Ramp view ([c-ramp.vue](https://github.com/reposense/RepoSense/blob/master/frontend/src/components/c-ramp.vue))

The `c_ramp` module is responsible for receiving the relevant information from `c_summary` and generating ramp charts that contain ramp slices.
The `c-ramp` module is responsible for receiving the relevant information from `c-summary` and generating ramp charts that contain ramp slices.

### Padding for dates
For ramps between the date ranges, the slices will be selected and it will be pre and post padded with empty slices to align the ramp slice between the `sinceDate` and `untilDate`. The ramps will then be rendered with the slices in the right position.
Expand All @@ -146,4 +147,4 @@ For ramps between the date ranges, the slices will be selected and it will be pr

## Segment view ([c-segment.vue](https://github.com/reposense/RepoSense/blob/master/frontend/src/components/c-segment.vue))

The `c-segment` module is used as a component in `c_authorship`. It separates the code in terms of "touched" and "untouched" segments and only loads each "untouched" segment when it is toggled.
The `c-segment` module is used as a component in `c-authorship`. It separates the code in terms of "touched" and "untouched" segments and only loads each "untouched" segment when it is toggled.
23 changes: 14 additions & 9 deletions docs/diagrams/ReportArchitecture.puml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,25 @@ hide footbox
skinparam monochrome true
skinparam Shadowing false

rectangle "main.js\n(window.app)" as main
rectangle "c_zoom.vue" as c_zoom
rectangle "c_ramp.vue" as c_ramp
rectangle "c_summary.vue" as c_summary
rectangle "c_authorship.vue" as c_authorship
rectangle "c_segment.vue" as c_segment
database "api.js\n" as api
rectangle "main.ts\n(window.app)" as main
rectangle "c-zoom.vue" as c_zoom
rectangle "c-ramp.vue" as c_ramp
rectangle "c-summary.vue" as c_summary
rectangle "c-authorship.vue" as c_authorship
rectangle "c-segment.vue" as c_segment
rectangle "c-home.vue" as c_home
rectangle "c-widget.vue" as c_widget
database "api.ts\n" as api

main -down-> c_summary
main -down-> c_home
main -down-> c_widget
c_home -down-> c_summary
c_widget -down-> c_summary
c_summary -down-> c_zoom
c_summary -> c_ramp
c_zoom -> c_ramp

main -down-> c_authorship
c_home -down-> c_authorship
c_authorship -down-> c_segment

api -down--> main : summary.json
Expand Down
8 changes: 4 additions & 4 deletions docs/diagrams/ReportArchitectureAuthorship.puml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@ hide footbox
skinparam monochrome true
skinparam Shadowing false

Participant ":Summary\n(c_summary.vue)" as summary
Participant ":Summary\n(c-summary.vue)" as summary
Participant ":Main\n(window.app)" as main
Participant ":Authorship\n(c_authorship.vue)" as authorship
Participant ":API\n(api.js)" as api
Participant ":Segment\n(c_segment.vue)" as segment
Participant ":Authorship\n(c-authorship.vue)" as authorship
Participant ":API\n(api.ts)" as api
Participant ":Segment\n(c-segment.vue)" as segment

-> summary : view code icon clicked
activate summary
Expand Down
6 changes: 3 additions & 3 deletions docs/diagrams/ReportArchitectureSummary.puml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ skinparam monochrome true
skinparam Shadowing false

Participant ":Main\n(window.app)" as main
Participant ":Summary\n(c_summary.vue)" as summary
Participant ":API\n(api.js)" as api
Participant ":Ramp\n(c_ramp.vue)" as ramp
Participant ":Summary\n(c-summary.vue)" as summary
Participant ":API\n(api.ts)" as api
Participant ":Ramp\n(c-ramp.vue)" as ramp

-> main : page load
activate main
Expand Down
Binary file modified docs/images/report-architecture.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
34 changes: 17 additions & 17 deletions docs/ug/authorConfigSyntax.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ To specify multiple `Repository's Location` in a single row, we can use a semico

Below is an example:

| Repository's Location | Branch | Author's Git Host ID | ... Hidden columns |
|-------------------------------------------------------------------------------------|---------|----------------------|-----------------------|
| https://github.com/reposense/RepoSense.git;https://github.com/MarkBind/markbind.git | master | sikai00 | -- |
| Repository's Location | Branch | Author's Git Host ID | ... Hidden columns |
|---------------------------------------------------------------------------------------|---------|----------------------|-----------------------|
| `https://github.com/reposense/RepoSense.git;https://github.com/MarkBind/markbind.git` | master | sikai00 | -- |

We have now furnished author details for both repositories in a single row, instead of having two individual rows per `Repository's Location`.

Expand All @@ -34,9 +34,9 @@ To list out one or more branches for a particular `Repository's Location`, we ca

Below is an example:

| Repository's Location | Branch | Author's Git Host ID | ... Hidden columns |
|----------------------------------------------------------------------|----------|----------------------|-----------------------|
| https://github.com/reposense/RepoSense.git~master\|release\|cypress | master | sikai00 | -- |
| Repository's Location | Branch | Author's Git Host ID | ... Hidden columns |
|------------------------------------------------------------------------|----------|----------------------|-----------------------|
| `https://github.com/reposense/RepoSense.git~master\|release\|cypress` | master | sikai00 | -- |

We have now provided author details for three different branches in a single repo, using a single row.

Expand All @@ -53,9 +53,9 @@ We can also use GitHub branch URL as copied from the address bar directly, to be

Below is an example:

| Repository's Location | Branch | Author's Git Host ID | ... Hidden columns |
|-----------------------------------------------------|----------|----------------------|-----------------------|
| https://github.com/reposense/RepoSense/tree/release | | sikai00 | -- |
| Repository's Location | Branch | Author's Git Host ID | ... Hidden columns |
|-------------------------------------------------------|----------|----------------------|-----------------------|
| `https://github.com/reposense/RepoSense/tree/release` | | sikai00 | -- |

There is no need to specify the `Branch` column now, as we have specified it through the GitHub branch URL.

Expand All @@ -70,16 +70,16 @@ GitLab and BitBucket branch URL are not supported at the moment.

It is possible to combine the above-mentioned advanced syntax. By doing so, we can go from:

| Repository's Location | Branch | Author's Git Host ID | ... Hidden columns |
|----------------------------------------------------------|----------|----------------------|-----------------------|
| https://github.com/MarkBind/markbind/tree/vue3-migration | | sikai00 | -- |
| https://github.com/reposense/RepoSense.git | master | sikai00 | -- |
| https://github.com/reposense/RepoSense.git | cypress | sikai00 | -- |
| Repository's Location | Branch | Author's Git Host ID | ... Hidden columns |
|------------------------------------------------------------|----------|----------------------|-----------------------|
| `https://github.com/MarkBind/markbind/tree/vue3-migration` | | sikai00 | -- |
| `https://github.com/reposense/RepoSense.git` | master | sikai00 | -- |
| `https://github.com/reposense/RepoSense.git` | cypress | sikai00 | -- |

to:

| Repository's Location | Branch | Author's Git Host ID | ... Hidden columns |
|---------------------------------------------------------------------------------------------------------------------|----------|----------------------|-----------------------|
| https://github.com/MarkBind/markbind/tree/vue3-migration;https://github.com/reposense/RepoSense.git~master\|cypress | | sikai00 | -- |
| Repository's Location | Branch | Author's Git Host ID | ... Hidden columns |
|-----------------------------------------------------------------------------------------------------------------------|----------|----------------------|----------------------|
| `https://github.com/MarkBind/markbind/tree/vue3-migration;https://github.com/reposense/RepoSense.git~master\|cypress` | | sikai00 | -- |

<br>

0 comments on commit 50dd4ab

Please sign in to comment.