Document the JS component tree

[guynir42]

It seems like it is getting harder and harder to find my way around the JS/components folder. There's a need for two things (maybe three): 1) Add a short code comment at the beginning of each file, saying e.g., "this is in the Source page, under the annotations table, etc.". 2) Make a readme file that quickly maps the tree of components, starting from main pages (e.g., candidates page, telescopes page). This could just be ascii with indentations for going deeper into the tree. In this file components that are re-used (e.g., SourceTable) could appear twice, under different branches. The goal is to help you figure out which file you need, when all you have is the a part of a page on the front end. 3) We could also add a graphical representation of this dependency tree. I personally am not sure that's more informative than just a text version but maybe that is more readable for other people.

NOTE: there could be automated tools to do this. If not, there could be a simple python script one could write to check the imports of each file (keeping only those imports local to the components folder) and building up a representation as e.g., nested dictionaries that are easy to print out later. Again, probably exists tools to do that out there.

NOTE 2: this could be a good issue for some of the new devs that are working on front end. A good opportunity to get to know the landscape.

[mcoughlin]

@Theodlz can we assign one of the students?

[Theodlz]

Yes @mcoughlin, I think that's a great idea. Maybe to a group of 2 students. They can easily devide the components folder in between them and do it a bit quicker.

[mcoughlin]

@Theodlz Maybe the Adrien's could knock this out?

[Theodlz]

Sounds good to me!

[mcoughlin]

@Adiman007 @KodeurFou Can you take a look?

[KodeurFou]

Here is the progress we've made so far:

We used dependency-cruiser to model the architecture of SP, we can see the react components and their relations

The graph is a little messy we tried having it displayed in a reactive way in an html format but so far no success

The problem we've had is it doesn't seem to be fitted to run on the same version of react that SP does

but the output we still get seems to be correct

should we try another way to try and automate the process or should we document the way we got it working so it can be re-rendered when some new components are added?

[mcoughlin]

@KodeurFou Could you open a PR that just pins the version of dependency-cruiser you are using to see if GA also struggles?

[guynir42]

It may also be a good place to consider if we want to split up the components folder into smaller subfolders...

[mcoughlin]

@guynir42 Interesting. How do you feel @Theodlz ?

[Theodlz]

It would be great. We could have a folder per page (or a folder per menu in the navbar basically). Of course some components we coded originally for a given page can be used on other pages, but thats not a problem. We could also have a "core" folder with all the reusable elements that we use very often on all pages.

[Theodlz]

Ah and also. Doing it in visual studio and not VIM, if you move a file, the imports are updated automagically. So it's an easy PR (just slow).

[mcoughlin]

@Theodlz Shots fired.

[guynir42]

I think this will make our code a lot more readable. I think having a "core" or "misc" folders would not be a bad idea. If you are not sure if a component belongs in one page-folder or another, put it in the core folder. This way it will take one or two tries to find a component instead of the mess we have now.