Document project interlinking

[glasnt]

What is the problem or limitation you are having?

Different BeeWare projects depend on each other, and we don't have a good picture of this interconnectivity documented at the moment.

Describe the solution you'd like

We need to provide a way for a new user to understand how all the pieces fit together. This might be a diagram of the "tech stack", showing how all the pieces fit together - or it could be a narrative description of the relationships.

Describe alternatives you've considered

Additional context

[goanpeca]

@glasnt sort of creating a dependency graph for all the tools, to produce a nice image?

[freakboy3742]

Agreed that this is definitely something where we are lacking. We need to revisit the homepage and project descriptions to give a better overall feel of how the project pieces fit together.

[VeldaKiara]

Would you be open to giving more context to help

[VeldaKiara]

Looking into this, for the sprint session today

[VeldaKiara]

Hey @freakboy3742

Here is the first draft I have, and I would love to get suggestions for it.

I had a few tweaks from @kattni and Baptiste

[freakboy3742]

So - apologies if I've led you astray here, but I'm not sure this is what is needed.

This is a nice graphical layout of the same project hierarchy that the website uses, but it doesn't really add any new information that isn't already conveyed by the website.

What is currently missing is an explanation of how all the pieces fit together. What's the relationship between Toga and Colosseum? What's the connection between Podium and Rubicon ObjC?

What we need is something that visualises relationships between the parts, not just enumerating the parts. I was thinking of this sort of diagram of the Android stack - something that shows how different pieces are layered on top of each other.

So - in terms of how the apps work at runtime, the apps are all at the top, sitting on top of Toga; Toga sits on Colosseum, which builds on Travertino (but Toga also sits on Travertino directly; Colosseum is an "alpha" project that isn't used actively); on macOS and iOS, Toga also sits on Rubicon ObjC. On GTK, Toga depends on PyGObject (which we don't maintain); on Windows, Toga depends on Python.net (which we don't maintain); on Android, Toga depends on Chaquopy (which isn't a BeeWare project, but shares a maintainer in Malcolm); on Web, Toga depends on PyScript (which we don't maintain); and on consol, Toga depends on Textual (which we don't maintain).

Then there's the packaging story. Each app is an output of Briefcase; and Briefcase depends on Python Apple Support (on iOS and macOS), Chaquopy (on Android), Linux system packges, and the official CPython Windows embedded build.

Now... how you put all that into a single diagram - especially the app vs deployment split.... I don't know :-)

Lastly - to be consistent with brand guidelines, any diagram headings should be using BeeWare's identity font - Cutive - and should be leaning toward sans-serif for longer text blocks.

[VeldaKiara]

Yes this actually helps, I also might have neglected to mention that this was the first part the second part would be adding information on the gutter on the side to share about the relationship. But I can figure out a way to show the relationship more using the above context

[johnzhou721]

@freakboy3742 Is this maybe a good proof of concept of what you're having in mind? This is very rough, and will need to be digitized in some way (maybe with LaTeX and friends, or I might find PowerPoint easier), and I've probably gotten a bunch of stuff wrong.

Edit

Maybe we can color-code some things and have a key for the platform -- that'd make it more clear. Also, do you want things that we depend upon but don't maintain in there? Maybe add an asterisk or something to indicate it's 3rd party.

[freakboy3742]

@johnzhou721 That's certainly closer to what I had in mind - although I'd definitely be looking for a much clearer "block with single name" layout for each piece, and less "annotations" on the side. Using different colors/shading would also be a given, as would digitising the image in a format that is widely editable - SVG would be my pick (definitely not Powerpoint, as it's a proprietary tool that many, including myself, don't have).

However, I'd also suggest that maybe you should leave this ticket to the person who opened it. You've already got multiple projects underway; I'd suggest focussing your attention on those, rather than adding another project that someone else is already working on.

[johnzhou721]

Nice suggestion. I've already took a stab on this -- using SVG and converted to PDF. Turns out we came up with some of the same things (less annotations) while I'm working. I don't use PowerPoint unless for school projects either (just realized that, it was a leftover memory from when I used to see my mom make flowcharts using it).

Shading is not done yet. Regarding multiple projects -- sorry I saw this too late and already did some initial work.

Question: Any trademarks BeeWare / Chaquopy has registered and any branding guidelines you have that would prevent me from putting this on my own repo (I will denote that it is UNOFFICIAL, though).

[johnzhou721]

Oh sorry I misread comment I thought less annotations in the blocks but you said on the side... Will need to simplify.

Edit

I also abstracted out the underlying C APIs Python Interpreter uses since it's not that important over here.