Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add a diagram for parts.rst #428

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+27 −0
Open

Add a diagram for parts.rst #428

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
89c5a39
Add a diagram for parts.rst
sed-i Apr 28, 2023
a454e50
Fix diagram
sed-i May 3, 2023
9140573
Add $ sign
sed-i May 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
"sphinx_autodoc_typehints", # must be loaded after napoleon
"sphinx-mermaid",
"sphinx-pydantic",
"sphinx_design",
"sphinxcontrib.details.directive",
Expand Down
25 changes: 25 additions & 0 deletions docs/explanation/parts.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,31 @@ describe a build process typically accept specifications of parts in YAML format
mostly-declarative format. Libraries that use parts may use the underlying
data structures to describe them.

.. mermaid ::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll give it a try.

Copy link

@ca-scribner ca-scribner May 16, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
...

?


graph LR

subgraph Part
$CRAFT_PART_SRC
$CRAFT_PART_BUILD
$CRAFT_PART_INSTALL
end

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

$CRAFT_PROJECT_DIR
--->|overlay| $CRAFT_OVERLAY
--->|stage| $CRAFT_STAGE

$CRAFT_PART_INSTALL
--->|organize| $CRAFT_PART_INSTALL


Describing a part
-----------------

Expand Down
1 change: 1 addition & 0 deletions docs/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Sphinx==5.3.0
sphinx-autobuild==2021.3.14
sphinx-autodoc-typehints==1.20.0
sphinx-jsonschema==1.19.1
sphinx-mermaid==0.0.8
sphinx-pydantic==0.1.1
sphinxcontrib-applehelp==1.0.2
sphinx_design==0.3.0
Expand Down