Netplan: Add netplan try to Netplan tutorial

[rkratky]

Context

While the Netplan docs already have a tutorial, it's missing information about the useful netplan try command. Further reasoning: it complements the netplan apply command, and it's been a well-received feature by the community.

Task

Showcase the netplan try command in the Applying new Netplan configuration section of the Netplan tutorial.

Reference

• Diataxis: Tutorial
• ReadTheDocs: Netplan documentation
• GitHub: netplan

[davidekete]

Hi @rkratky , I'd like to work on this

[rkratky]

Great, thanks for your interest, @davidekete. I assigned the item to you.

[davidekete]

Hi @rkratky, I'm done with this. I'm currently trying to open a PR to the netplan repo but I'm having an issue with the check list.
Particularly these two:

• Runs make check successfully.
• Retains 100% code coverage (make check-coverage).

Running make check throws the error below:

Sphinx error:
Builder name check not registered or available through entry point

Running make check-coverage throws a similar error:

Sphinx error:
Builder name check-coverage not registered or available through entry point

can you help?

[rkratky]

Those commands are meant to be run from the root directory of the repo, not from the doc/ directory. The error messages are telling you that the Makefile (in the doc/ directory) does not have check and check-coverage targets defined. These targets are defined in the Makefile that's in the repo's main directory.

user@machine:netplan/doc$ cd ..
user@machine:netplan$ make check
user@machine:netplan$ make check-coverage

[davidekete]

Hi, thanks for the correction. I had tried that initially but got a weird error. However, after your comment, I took a look and got past the error. After that, I faced a lot of other errors related to missing dependencies. However, I still can't get it to run after installing them. Here's what I'm getting currently.

meson.build:82:0: ERROR: Tried to use not-found external program as test exe

Can you help?

[davidekete]

Hi, thanks for the correction. I had tried that initially but got a weird error. However, after your comment, I took a look and got past the error. After that, I faced a lot of other errors related to missing dependencies. However, I still can't get it to run after installing them. Here's what I'm getting currently.

meson.build:82:0: ERROR: Tried to use not-found external program as test exe

Can you help?

Hi @rkratky, Just following up on this

[rkratky]

Apologies for the silence. I should be able to look into it tomorrow.

Could you please push the branch to your fork (no need to create a PR just yet), so that I could pull it and work with exactly the same as what you have?

[davidekete]

Hi @rkratky, no problem. I have pushed the changes to my fork. Here's the link.

[rkratky]

meson.build:82:0: ERROR: Tried to use not-found external program as test exe

Line 82 in meson.build says test('codestyle', so you need to install the codestyle tool to be able to run the specified test. You can find it in the pycodestyle package on Ubuntu.

That said, I've now run the tests, and I see there are some errors in the code, but nothing that would be caused by the changes you introduced. So, you're good to go.

Please, submit a PR against the Netplan repo.

............

One suggestion: In step 3 of the procedure you modified, you added a note:

"Skip this step if you confirmed the changes using netplan try."

I think that could be confusing because while netplan try requires the user to confirm the changes to make them permanent, 'confirm' can also mean just "verify that the changes are OK". i'd suggest saying explicitly something like:

"Skip this step if you made the changes permanent using netplan try."

.............

One correction:

"Applies the new configuration temporarily (120 seconds by default) and waits for confirmation (within the specified time) to make them permanent."

->

"Applies the new configuration temporarily (120 seconds by default) and waits for confirmation (within the specified time) to make it permanent."

[davidekete]

Hi @rkratky, thank you for your help, the suggestion, and the correction. I have applied them and opened the PR. I wanted to know if we could add setting up a local development environment guide for the Netplan docs. It took me a while to do it, and I imagine others might have encountered the same issues. What do you think?

[rkratky]

Hi @rkratky, thank you for your help, the suggestion, and the correction. I have applied them and opened the PR.

👍

I wanted to know if we could add setting up a local development environment guide for the Netplan docs. It took me a while to do it, and I imagine others might have encountered the same issues. What do you think?

I suppose this would be an extension of https://canonical-netplan.readthedocs-hosted.com/en/latest/contribute-docs/

• You're right that there could be more. I think there's enough about the actual docs, but it could include a short section on how to do what's needed in order to open a PR (i.e. satisfy the conditions for actual Netplan development).
• And it could better placed -- now it's rather hidden among all the other howtos.

[davidekete]

Yes, an extension of https://canonical-netplan.readthedocs-hosted.com/en/latest/contribute-docs/, which I agree should be better placed (I'm just finding out it exists). I'm glad you agree. Can you open another issue and assign it to me?

[rkratky]

I created the issue: #122. But you need to comment under the issue before the system let's me assign it to you.

[davidekete]

I created the issue: #122. But you need to comment under the issue before the system let's me assign it to you.

Thank you. I just commented. Any update on my open PR: canonical/netplan#494. The spell checker failed but it wasn't due to any changes I made.

[rkratky]

Completed. Thank you, @davidekete!