Add documentation for VC database fields

[mjherzog]

We need to add Reference documentation for the VulnerableCode database fields. Perhaps we can regenerate the diagrams that @johnmhoran created about a month ago (copies attached). We may need to figure out how to create them in a narrower width format because is it annoying to scroll for this type of diagram - see https://vulnerablecode.readthedocs.io/en/latest/reference_framework_overview.html.
This may be the time to widen our RTD page format.

[mjherzog]

[pombredanne]

As an example we generate models docs in SCIO here https://scancodeio.readthedocs.io/en/latest/data-models.html

[mjherzog]

@johnmhoran We need to widen this page in the RTD as you did for the Audit/Analysis/SPATS RTD. There are already 2 tables there that you cannot read in portrait-only format so we need landscape even before considering how to display a DB diagram. It would be best if you can just widen the page for now since we have not polled the team on changing look & feel overall.

[johnmhoran]

Will do @mjherzog .

[johnmhoran]

@mjherzog I've added some simple CSS and folder structure etc. and the vulnerablecode RTD page now has the wide look of the other RTD. The latter has much more CSS for various widgets, dropdowns, a navbar etc. and I'm not proposing we add all of that to the vulnerablecode RTD. However, before I commit and push I could show you what we now have locally and get any immediate additional feedback you might have. Comparisons pasted below. How would you like to proceed?

Before:

After:

[mjherzog]

Please proceed with the width change for now. I think that we will want to make landscape and a default and add some or all of the other features from the private RTDs, but we need to engage a broader group who are interested in our doc style. I am guessing Ayan, Dennis, Thomas and Philippe, but we need to open the floor to all nexB people and likely the AboutCode community people who are interested.

[johnmhoran]

OK.

[johnmhoran]

@mjherzog I've reviewed my 2022 notes, created a new test branch, loaded/installed various packages including graphviz, and my initial simple command produced this -- a start.

[mjherzog]

@johnmhoran Thank you for the diagram! It seems from top-down that there are two major chunks here:

• The application data which includes everything from left-to-right including Advisory
• The admin data which includes everything from left-to-right starting with Token Proxy
  So it would be nice to somehow split this into 2 diagrams along those lines.

[johnmhoran]

@mjherzog Here's an example of the application group:

and the admin group:

[mjherzog]

We should add these to the VulnerableCode RTD documentation - presumably a new sub-section in the Reference section.

[johnmhoran]

@mjherzog I've added a new Model Overview page to the vulnerablecode RTD containing the application and admin graph diagrams generated with Graphviz. You can see the initial draft here:

https://vulnerablecode--1350.org.readthedocs.build/en/1350/reference_model_overview.html

[mjherzog]

The diagrams look good. We will need a process to keep them in sync with Model changes over time, but closing this Issue because it has been completed.