[Docs] Update PyTorch tutorial

[adarshan-intel]

Description of the Changes

This Pull Request (PR) addresses documentation updates in the Gramine project, influenced by changes made in gramineproject/examples#109

How to Test This PR?

This PR should be merged after the completion and merging of gramineproject/examples#109

---

This change is 

[efu39]

Reviewed 1 of 1 files at r1, all commit messages.
Reviewable status: all files reviewed, all discussions resolved, not enough approvals from maintainers (3 more required), not enough approvals from different teams (2 more required, approved so far: )

[adarshan-intel]

@kailun-qin Please review

[kailun-qin]

Reviewed 1 of 1 files at r1, all commit messages.
Reviewable status: all files reviewed, 5 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ) (waiting on @adarshan-intel)

---

-- commits line 2 at r1:
-> [Docs] Update PyTorch tutorial

Code quote:

[Docs] Update pytorch docs to add support for Ubuntu 24.04

---

Documentation/tutorials/pytorch/index.rst line 95 at r1 (raw file):

  the compute platform).

- Gramine v1.8, with DCAP support. DCAP software infrastructure must also be

We remove the notes above but we still pin to a specific Gramine version?

Code quote:

Gramine v1.8

---

Documentation/tutorials/pytorch/index.rst line 102 at r1 (raw file):

.. warning::

   After running Ubuntu 24.04, it is highly recommended to use a virtual environment to manage

Is this recommended or required for Ubuntu 24.04?

Code quote:

After running Ubuntu 24.04, it is highly recommended to use a virtual environment

---

Documentation/tutorials/pytorch/index.rst line 124 at r1 (raw file):

Go to the directory with Gramine's PyTorch example::

   git clone --depth 1 --branch v1.8 https://github.com/gramineproject/examples.git

ditto (pin to specific version). And this branch does not contain your updates to the PyTorch example -- meaning that this won't actually work for Ubuntu 24.04?

Code quote:

--branch v1.8

---

Documentation/tutorials/pytorch/index.rst line 377 at r1 (raw file):

repository), so let's build the secret provisioning server::

   git clone --depth 1 --branch v1.8 https://github.com/gramineproject/gramine.git

ditto

Code quote:

v1.8

[adarshan-intel]

Reviewable status: all files reviewed, 5 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ) (waiting on @kailun-qin)

---

-- commits line 2 at r1:

Previously, kailun-qin (Kailun Qin) wrote…

-> [Docs] Update PyTorch tutorial

Done.

---

Documentation/tutorials/pytorch/index.rst line 95 at r1 (raw file):

Previously, kailun-qin (Kailun Qin) wrote…

We remove the notes above but we still pin to a specific Gramine version?

Done.
Removing pinning of versions

---

Documentation/tutorials/pytorch/index.rst line 102 at r1 (raw file):

Previously, kailun-qin (Kailun Qin) wrote…

Is this recommended or required for Ubuntu 24.04?

It is a must case, so making it required

---

Documentation/tutorials/pytorch/index.rst line 124 at r1 (raw file):

Previously, kailun-qin (Kailun Qin) wrote…

ditto (pin to specific version). And this branch does not contain your updates to the PyTorch example -- meaning that this won't actually work for Ubuntu 24.04?

Done.
Removing pinning of versions

---

Documentation/tutorials/pytorch/index.rst line 377 at r1 (raw file):

Previously, kailun-qin (Kailun Qin) wrote…

ditto

Done.

[kailun-qin]

Reviewed 1 of 1 files at r2, all commit messages.
Reviewable status: all files reviewed, 3 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ), "fixup! " found in commit messages' one-liners (waiting on @adarshan-intel)

---

Documentation/tutorials/pytorch/index.rst line 99 at r2 (raw file):

Please refer to the `Gramine Attestation Documentation
<https://gramine.readthedocs.io/en/latest/attestation.html>`__ for more details.

Pls align and wrap.

Code quote:

- Gramine with DCAP support. DCAP software infrastructure must also be
   installed.

Please refer to the `Gramine Attestation Documentation
<https://gramine.readthedocs.io/en/latest/attestation.html>`__ for more details.

[kailun-qin]

Reviewable status: all files reviewed, 4 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ), "fixup! " found in commit messages' one-liners (waiting on @adarshan-intel)

---

-- commits line 2 at r1:

Previously, adarshan-intel (Adarsh Anand) wrote…

Done.

Not done?

---

Documentation/tutorials/pytorch/index.rst line 124 at r1 (raw file):

Previously, adarshan-intel (Adarsh Anand) wrote…

Done.
Removing pinning of versions

But why remove --depth 1?

---

Documentation/tutorials/pytorch/index.rst line 377 at r1 (raw file):

Previously, adarshan-intel (Adarsh Anand) wrote…

Done.

But why remove --depth 1?

[woju]

Reviewed 1 of 1 files at r2, all commit messages.
Reviewable status: all files reviewed, 6 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ), "fixup! " found in commit messages' one-liners (waiting on @adarshan-intel and @kailun-qin)

---

Documentation/tutorials/pytorch/index.rst line 377 at r1 (raw file):

Previously, kailun-qin (Kailun Qin) wrote…

But why remove --depth 1?

This is wrong: when you clone something from git without pinning to a tag, you might get newer version than packages support. Recently we had this problem with entrypoint: the option was removed from manifests in examples, but the released (packaged) version still required it, so if someone just cloned examples, they didn't work. So no, you need to keep --branch.

If you want this to be moved to last stable release, you can use |stable-checkout| like this (note parsed-literal instead of ::-block):

.. parsed-literal::

   git clone --depth 1 |stable-checkout| \https://github.com/gramineproject/examples.git

cf.:

gramine/Documentation/run-sample-application.rst

Lines 9 to 11 in 5789620

	.. parsed-literal::
	git clone --depth 1 |stable-checkout| \https://github.com/gramineproject/gramine.git

I'm not sure about examples.git, they might be OK to just clone, so I didn't block the other discussion.

---

Documentation/tutorials/pytorch/index.rst line 88 at r2 (raw file):

-------------

- A Linux-based operating system (e.g., Ubuntu 20.04 or later)

Gramine supports 22.04 or later, please update. I know that maybe this howto works with 20.04, but we don't want people to file issues for 20.04 anymore.

Suggestion:

Ubuntu 22.04

---

Documentation/tutorials/pytorch/index.rst line 103 at r2 (raw file):

.. warning::

   After running Ubuntu 24.04, it is required to use a virtual environment to manage

"After running Ubuntu 24.04" sounds weird, needs to be rephrased. Something like "If you're on a recent distro that implements PEP 668 (e.g. Debian 12, Ubuntu 24.04), it is required ..."?

[adarshan-intel]

Reviewable status: all files reviewed, 6 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ), "fixup! " found in commit messages' one-liners (waiting on @kailun-qin and @woju)

---

-- commits line 2 at r1:

Previously, kailun-qin (Kailun Qin) wrote…

Not done?

Done.

---

Documentation/tutorials/pytorch/index.rst line 124 at r1 (raw file):

Previously, kailun-qin (Kailun Qin) wrote…

But why remove --depth 1?

Done.

---

Documentation/tutorials/pytorch/index.rst line 377 at r1 (raw file):

Previously, woju (Wojtek Porczyk) wrote…

This is wrong: when you clone something from git without pinning to a tag, you might get newer version than packages support. Recently we had this problem with entrypoint: the option was removed from manifests in examples, but the released (packaged) version still required it, so if someone just cloned examples, they didn't work. So no, you need to keep --branch.

If you want this to be moved to last stable release, you can use |stable-checkout| like this (note parsed-literal instead of ::-block):

.. parsed-literal::

   git clone --depth 1 |stable-checkout| \https://github.com/gramineproject/examples.git

cf.:

gramine/Documentation/run-sample-application.rst

Lines 9 to 11 in 5789620

	.. parsed-literal::
	git clone --depth 1 |stable-checkout| \https://github.com/gramineproject/gramine.git

I'm not sure about examples.git, they might be OK to just clone, so I didn't block the other discussion.

I believe cloning examples repo would be just fine, as of not just keeping to latest commit with depth 1 will change upon request

---

Documentation/tutorials/pytorch/index.rst line 88 at r2 (raw file):

Previously, woju (Wojtek Porczyk) wrote…

Gramine supports 22.04 or later, please update. I know that maybe this howto works with 20.04, but we don't want people to file issues for 20.04 anymore.

Done.

---

Documentation/tutorials/pytorch/index.rst line 99 at r2 (raw file):

Previously, kailun-qin (Kailun Qin) wrote…

Pls align and wrap.

Done.

---

Documentation/tutorials/pytorch/index.rst line 103 at r2 (raw file):

Previously, woju (Wojtek Porczyk) wrote…

"After running Ubuntu 24.04" sounds weird, needs to be rephrased. Something like "If you're on a recent distro that implements PEP 668 (e.g. Debian 12, Ubuntu 24.04), it is required ..."?

Done.

[woju]

Reviewed 1 of 1 files at r3, all commit messages.
Reviewable status: all files reviewed, 4 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ), "fixup! " found in commit messages' one-liners (waiting on @kailun-qin)

---

-- commits line 2 at r1:

Previously, adarshan-intel (Adarsh Anand) wrote…

Done.

No, you didn't. You need to either rework the commits itself (git commit --amend and/or git rebase -i --autosquash $(git merge-base HEAD origin/master) — be careful not to move branch base, because it messes reviewer's workflow), or you need to post amend! commit (git commit --fixup=amend:...) for this review discussion to be "Done".

---

Documentation/tutorials/pytorch/index.rst line 377 at r1 (raw file):

Previously, adarshan-intel (Adarsh Anand) wrote…

I believe cloning examples repo would be just fine, as of not just keeping to latest commit with depth 1 will change upon request

Yes, but here you clone gramine.git itself. As I explained, you need to specify --branch, either explicitly, or through |stable-checkout|.

[adarshan-intel]

Documentation/tutorials/pytorch/index.rst line 377 at r1 (raw file):

Previously, woju (Wojtek Porczyk) wrote…

Yes, but here you clone gramine.git itself. As I explained, you need to specify --branch, either explicitly, or through |stable-checkout|.

Earlier, I was confused why |stable-checkout| was not working. Then I wrapped it with backticks (``), and it worked. I believe this is what you were suggesting?

[adarshan-intel]

Reviewable status: 0 of 1 files reviewed, 4 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ) (waiting on @kailun-qin and @woju)

---

-- commits line 2 at r1:

Previously, woju (Wojtek Porczyk) wrote…

No, you didn't. You need to either rework the commits itself (git commit --amend and/or git rebase -i --autosquash $(git merge-base HEAD origin/master) — be careful not to move branch base, because it messes reviewer's workflow), or you need to post amend! commit (git commit --fixup=amend:...) for this review discussion to be "Done".

I have done interactive rebase.
Can you check if it is done now?

[kailun-qin]

Reviewed 1 of 1 files at r4, all commit messages.
Reviewable status: all files reviewed, 2 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ) (waiting on @woju)

---

Documentation/tutorials/pytorch/index.rst line 377 at r1 (raw file):

Then I wrapped it with backticks (``), and it worked

What you mean by working?

I think what woju was suggesting is to use the parsed-literal reST directive for that "git clone ..." block of text, same as here:

gramine/Documentation/run-sample-application.rst

Lines 9 to 11 in 5789620

	.. parsed-literal::
	git clone --depth 1 |stable-checkout| \https://github.com/gramineproject/gramine.git

.

[adarshan-intel]

Documentation/tutorials/pytorch/index.rst line 377 at r1 (raw file):

Previously, kailun-qin (Kailun Qin) wrote…

Then I wrapped it with backticks (``), and it worked

What you mean by working?

I think what woju was suggesting is to use the parsed-literal reST directive for that "git clone ..." block of text, same as here:

gramine/Documentation/run-sample-application.rst

Lines 9 to 11 in 5789620

	.. parsed-literal::
	git clone --depth 1 |stable-checkout| \https://github.com/gramineproject/gramine.git

.

Something like this?

[adarshan-intel]

Documentation/tutorials/pytorch/index.rst line 377 at r1 (raw file):

Previously, adarshan-intel (Adarsh Anand) wrote…

Something like this?

But when I run make html, the documentation doesn’t display correctly

[woju]

Reviewed 1 of 1 files at r8, all commit messages.
Reviewable status: all files reviewed, 3 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ), "fixup! " found in commit messages' one-liners (waiting on @adarshan-intel and @kailun-qin)

---

-- commits line 2 at r1:

Previously, adarshan-intel (Adarsh Anand) wrote…

I have done interactive rebase.
Can you check if it is done now?

Yes, you did rebase, but you didn't change the title of the commit as @kailun-qin asked (and then proceeded to add a couple of extra fixup! commits). Still not done.

---

Documentation/tutorials/pytorch/index.rst line 377 at r1 (raw file):

Previously, adarshan-intel (Adarsh Anand) wrote…

But when I run make html, the documentation doesn’t display correctly

Yes, that's expected: it's hidden until you tag the version and add READTHEDOCS=1 READTHEDOCS_VERSION=stable to make html. Unless you do that, it will be hidden, as it should.

There's a catch though, it currently fails without this PR: #2073.

make clean
git tag v123456-TEST
make html READTHEDOCS=1 READTHEDOCS_VERSION=stable
git tag -d v123456-TEST
firefox _build/html/index.html

So this particular section LGTM. I've tested it provisionally rebased on top of #2073 and it works fine (with double-colon fixed to single colon):

---

Documentation/tutorials/pytorch/index.rst line 376 at r8 (raw file):

We will use the reference implementation of the Secret Provisioning server found
under ``CI-Examples/ra-tls-secret-prov`` directory (in the core Gramine
repository), so let's build the secret provisioning server::

This double colon you need to fix to single colon for the block to render properly (see screenshot in next discussion).

Suggestion:

server:

[adarshan-intel]

-- commits line 2 at r1:

Yes, you did rebase, but you didn't change the title of the commit as @kailun-qin asked (and then proceeded to add a couple of extra fixup! commits). Still not done.

In my commit history I can see the name, [Docs] Update PyTorch tutorial, this is the name which is expected right?
Or am I missing something>

[adarshan-intel]

Documentation/tutorials/pytorch/index.rst line 376 at r8 (raw file):

Previously, woju (Wojtek Porczyk) wrote…

This double colon you need to fix to single colon for the block to render properly (see screenshot in next discussion).

Done

[adarshan-intel]

Reviewable status: 0 of 1 files reviewed, 3 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ), "fixup! " found in commit messages' one-liners (waiting on @kailun-qin and @woju)

---

Documentation/tutorials/pytorch/index.rst line 377 at r1 (raw file):

Previously, woju (Wojtek Porczyk) wrote…

Yes, that's expected: it's hidden until you tag the version and add READTHEDOCS=1 READTHEDOCS_VERSION=stable to make html. Unless you do that, it will be hidden, as it should.

There's a catch though, it currently fails without this PR: #2073.

make clean
git tag v123456-TEST
make html READTHEDOCS=1 READTHEDOCS_VERSION=stable
git tag -d v123456-TEST
firefox _build/html/index.html

So this particular section LGTM. I've tested it provisionally rebased on top of #2073 and it works fine (with double-colon fixed to single colon):

Done.

[woju]

Reviewed 1 of 1 files at r9, all commit messages.
Reviewable status: all files reviewed, 3 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ), "fixup! " found in commit messages' one-liners (waiting on @adarshan-intel and @kailun-qin)

---

-- commits line 2 at r1:

Previously, adarshan-intel (Adarsh Anand) wrote…

Yes, you did rebase, but you didn't change the title of the commit as @kailun-qin asked (and then proceeded to add a couple of extra fixup! commits). Still not done.

In my commit history I can see the name, [Docs] Update PyTorch tutorial, this is the name which is expected right?
Or am I missing something>

Ah, ok. I misread, sorry for the confusion.

---

Documentation/tutorials/pytorch/index.rst line 376 at r8 (raw file):

Previously, adarshan-intel (Adarsh Anand) wrote…

Done

Not done, wrong server::.

---

Documentation/tutorials/pytorch/index.rst line 446 at r9 (raw file):

and use them.

Now we can launch the secret provisioning server:

This was OK, please revert.

Suggestion:

server::

[adarshan-intel]

Reviewable status: 0 of 1 files reviewed, 3 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (2 more required, approved so far: ), "fixup! " found in commit messages' one-liners (waiting on @kailun-qin and @woju)

---

Documentation/tutorials/pytorch/index.rst line 376 at r8 (raw file):

Previously, woju (Wojtek Porczyk) wrote…

Not done, wrong server::.

Done.
Good catch, I made changes at other place.

---

Documentation/tutorials/pytorch/index.rst line 446 at r9 (raw file):

Previously, woju (Wojtek Porczyk) wrote…

This was OK, please revert.

Done.

[kailun-qin]

Reviewed 1 of 1 files at r10, all commit messages.
Reviewable status: all files reviewed, 2 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @woju)

[adarshan-intel]

Reviewable status: all files reviewed, 2 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @woju)

---

Documentation/tutorials/pytorch/index.rst line 376 at r8 (raw file):

Previously, adarshan-intel (Adarsh Anand) wrote…

Done.
Good catch, I made changes at other place.

Done

---

Documentation/tutorials/pytorch/index.rst line 446 at r9 (raw file):

Previously, adarshan-intel (Adarsh Anand) wrote…

Done.

Done

[adarshan-intel]

@woju Have updated the server: typo at both places, any more changes TODO ?

Reviewable status: all files reviewed, 2 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @woju)