Add a diagram for parts.rst

[sed-i]

This PR adds a diagram to the "parts" doc.
Edit a live copy of the diagram here.

[sed-i]

@cmatsuoka @cjdcordeiro @tigarmo wdyt about this as a quick-glance reference?
Surely still needs to be polished.

[cjdcordeiro]

I think mermaid would be a nice addition to the docs, to avoid static content

[tigarmo]

I like this high-level diagram but I'm wondering about its position here; there is a Lifecycle-specific page with similar-but-different diagram (here), but I don't know if things are organized as well as they could be.
@dboddie can you take a look at this page, and the Lifecycle page, and give your opinion here?

[dboddie]

It's a good start but I'll need to fix up the configuration and modify the diagram to fit it onto the page. It's a bit wide at the moment.

[sed-i]

Thanks @dboddie.
If the width is not autoscaled then perhaps graph TD would look better than graph LR?

[dboddie]

I'll give it a try.

[ca-scribner]

EDIT: Whoops, I originally comment on an old version of the figure. Comment is updated now

This diagram is great and with a few minor tweaks I think it'll be fantastic in the docs.

I like that the nodes are now $CRAFT_PART_INSTALL, etc. That imo makes it clear they represent the directories. maybe that makes the nodes a bit odd to read at first, but if there's some text explaining that above the diagram it'll be fine I think

For the arrows, again some text explaining these are state transitions would be helpful. Linking them directly to commands (the build transition corresponds to *craft build, etc) would be even better.

I wonder if we can clarify the build transition. iiuc, build gets a copy of $CRAFT_PART_SRC to work on in $CRAFT_PART_BUILD, and then build is responsible for putting anything that'll go to organize/stage into CRAFT_PART_INSTALL? Does the user have any control over the copying of $CRAFT_PART_SRC to $CRAFT_PART_BUILD? The diagram makes me think it does, but I don't think that's correct (if I do override-build. For example, if you do override-build, you still get a populated $CRAFT_PART_SRC dir to start with (at least, I did when overriding the go plugin). Maybe there's a different way to represent this. Like...

...
$CRAFT_PROJECT_DIR 
--->|pull| $CRAFT_PART_SRC
--->|preprocessing for build| $CRAFT_PART_BUILD
--->|build| $CRAFT_PART_INSTALL
--->|stage| $CRAFT_STAGE
--->|prime| $CRAFT_PRIME
...

?

[sed-i]

Hi @tigarmo, @cmatsuoka, @cjdcordeiro,
If you still think this diagram is worthwhile to have, I can convert it to drawio + export to png under docs/images.
Otherwise please feel free to close this PR.

[cjdcordeiro]

Hey,

in the meantime, this new image was drafted:

We have already used it in a couple of places and might consider cleaning it up to include in (some) docs. There's a big doc refactoring item coming up over the next few months, so I'd keep these images in our watchlist for now.