Fix docs directory structure to reflect diátaxis #520

davidekete · 2024-09-24T18:57:31Z

Description

Addresses canonical/open-documentation-academy#125

Checklist

Runs make check successfully.
Retains code coverage (make check-coverage).
New/changed keys in YAML format are documented.
(Optional) Adds example YAML for new feature.
(Optional) Closes an open bug in Launchpad.

Meson and docs-validation updates to reflect new docs dir structure.

rkratky · 2024-09-25T08:51:40Z

@davidekete, thanks for submitting this! To fix the spellcheck and one cross-doc link, I submitted a PR against your branch: davidekete#3

Fix paths to reference docs for link and spellcheck.

davidekete · 2024-09-25T09:23:56Z

@davidekete, thanks for submitting this! To fix the spellcheck and one cross-doc link, I submitted a PR against your branch: davidekete#3

Thank you. I just merged the PR.

rkratky · 2024-09-25T11:50:50Z

Two notes:

@davidekete, as discussed on Matrix, could you please rename the main/landing files in the individual categories to index.md? This naming convention is used in all other Ubuntu docs published on RTD, so it'd be good to keep it consistent. Also, it'd avoid the duplication that results from Sphinx building the landing page in two places when the index file is absent.
@slyon, while this change in directory structure is certainly an improvement for the repo, it'll mean some existing URLs would no longer work. Therefore, we need redirects. My question is: do you think it would be enough to add redirects for the main categories only (i.e. explanation, howto, ...), or do we need redirects for all existing pages?

slyon · 2024-09-25T14:23:50Z

do we need redirects for all existing pages?

I think the most important one would be the netplan-yaml reference. Maybe that in combination with the main categories. And also making sure that our website still points to the correct reference, e.g.: https://netplan.io/reference

…tps://github.com/davidekete/netplan into Fix-docs-directory-structure-to-reflect-Diátaxis

davidekete · 2024-09-25T20:37:53Z

Two notes:

@davidekete, as discussed on Matrix, could you please rename the main/landing files in the individual categories to index.md? This naming convention is used in all other Ubuntu docs published on RTD, so it'd be good to keep it consistent. Also, it'd avoid the duplication that results from Sphinx building the landing page in two places when the index file is absent.

@slyon, while this change in directory structure is certainly an improvement for the repo, it'll mean some existing URLs would no longer work. Therefore, we need redirects. My question is: do you think it would be enough to add redirects for the main categories only (i.e. explanation, howto, ...), or do we need redirects for all existing pages?

@rkratky, I have renamed them as index.md and updated the references to match the names.

rkratky · 2024-10-04T14:49:31Z

@slyon, I believe this is good to be merged. Could you please have a look?

slyon

Sorry for the late review and thank you very much for your contribution to Netplan!

In general this looks fine, but it also breaks lots of references around the internet. I wonder if the benefit is great enough to justify that? I see that have this new structure would improve the maintainability going forward... @rkratky what's your stance on this? Is there any recommendation from the technical authors?

I'd be fine with merging it once we fix the broken internal references (see inline comments of certian "howto" files) and the outside-references to netplan-yaml, using anchor redirects. This would be the bare minimum, I guess.

slyon · 2024-10-09T16:00:26Z

doc/conf.py

@@ -121,7 +121,7 @@

 redirects = {
    'README.md': '/',
-    'netplan': '/netplan-yaml',
+    'netplan': '/reference/netplan-yaml',


todo: I'm still missing a redirect for the old netplan-yaml here.

In the end, we need to be able to redirect something like https://netplan.io/reference#routing to https://netplan.readthedocs.io/en/latest/reference/netplan-yaml/#routing

I was unable to make the sphinx-reredirects redirect any anchor (i.e. the URI fragment after the hashtag #routing), but this is important for the netplan-yaml page, as there are lots of deep links aroud the internet pointing to specific configuration and we would break all of them if we don't support redirecting to the proper anchor.

@rkratky Do you have any idea how anchor redirects could be solved?

When you say you're missing a redirect for the old netplan-yaml, what do you mean @slyon?

doc/howto/multi-nic-vm-host-with-bonds-and-vlans.md

doc/howto/single-nic-vm-host-with-vlans.md

doc/howto/single-nic-vm-host.md

doc/howto/netplan-everywhere.md

rkratky · 2024-10-10T11:14:46Z

In general this looks fine, but it also breaks lots of references around the internet.

Yes, that's my main concern, too.

I wonder if the benefit is great enough to justify that? I see that have this new structure would improve the maintainability going forward... @rkratky what's your stance on this? Is there any recommendation from the technical authors?

I believe the benefits outweigh the negatives (I suggested this change).

slyon · 2024-10-14T15:01:34Z

I believe the benefits outweigh the negatives (I suggested this change).

@rkratky ACK, fair enough. Would you be able to assist with the critical redirects for the netplan-yaml page, then? E.g. https://netplan.io/reference#routing to https://netplan.readthedocs.io/en/latest/reference/netplan-yaml/#routing ?

rkratky · 2024-10-15T10:27:46Z

Would you be able to assist with the critical redirects

Yes, I hope. Just acknowledging now because I'm not sure if I'll get to it this week, i.e. before the Sprints.

davidekete · 2024-10-15T22:26:32Z

Would you be able to assist with the critical redirects

Yes, I hope. Just acknowledging now because I'm not sure if I'll get to it this week, i.e. before the Sprints.

Hi @rkratky, @slyon, I could work on this myself to speed up the process. I just need a little more context to what needs to be done and i'll get righ on it.

slyon · 2024-10-16T11:26:55Z

Would you be able to assist with the critical redirects

Yes, I hope. Just acknowledging now because I'm not sure if I'll get to it this week, i.e. before the Sprints.

Hi @rkratky, @slyon, I could work on this myself to speed up the process. I just need a little more context to what needs to be done and i'll get righ on it.

@davidekete Thanks, that's appreciated! See my inline comments above, there are some easy TODOs in there for you, e.g. fixing the include path for the "reuse" documents.

After that we need to find a way to allow Sphinx/ReadTheDocs to redirect URLs with an anchor, like this: https://netplan.io/reference#routing to https://netplan.readthedocs.io/en/latest/reference/netplan-yaml/#routing (preserving the "#routing" fragment). I don't know how this works and wasn't able to find a way when quickly looking into that.

Furthermore, there seems to be a merge conflict in doc/netplan-yaml.md by now (sorry for taking so long), which needs to be resolved.

…-docs-directory-structure-to-reflect-Diátaxis

davidekete · 2024-10-20T00:43:03Z

Would you be able to assist with the critical redirects

Yes, I hope. Just acknowledging now because I'm not sure if I'll get to it this week, i.e. before the Sprints.

Hi @rkratky, @slyon, I could work on this myself to speed up the process. I just need a little more context to what needs to be done and i'll get righ on it.

@davidekete Thanks, that's appreciated! See my inline comments above, there are some easy TODOs in there for you, e.g. fixing the include path for the "reuse" documents.

After that we need to find a way to allow Sphinx/ReadTheDocs to redirect URLs with an anchor, like this: https://netplan.io/reference#routing to https://netplan.readthedocs.io/en/latest/reference/netplan-yaml/#routing (preserving the "#routing" fragment). I don't know how this works and wasn't able to find a way when quickly looking into that.

Furthermore, there seems to be a merge conflict in doc/netplan-yaml.md by now (sorry for taking so long), which needs to be resolved.

Hi @slyon, I fixed most of the Todos. I tried to find a way to allow Sphinx/ReadTheDocs to redirect URLs with an anchor, but I couldn't; this is new territory for me. Could you explain the background of the problem? and If you figure out a way to solve it, could you explain that to me too?

slyon

Hi @slyon, I fixed most of the Todos. I tried to find a way to allow Sphinx/ReadTheDocs to redirect URLs with an anchor, but I couldn't; this is new territory for me. Could you explain the background of the problem? and If you figure out a way to solve it, could you explain that to me too?

Thanks for solving the merge conflicts and the ../reuse/... imports! I left two more inline-comments, about an (apparently?) unrelated change and an additional redirect.

Regarding the anchor redirect, that you asked about:
We need to find a way to redirect URLs with an anchor, like this: https://netplan.io/reference#routing or https://netplan.readthedocs.io/en/latest/netplan-yaml/#routing to the new URL at https://netplan.readthedocs.io/en/latest/reference/netplan-yaml/#routing – The important part being the #routing fragment/section here.

There are lots of links out on AskUbuntu, Launchpad and other places, that are deep links into the reference document (netplan-yaml) and we need to make sure those are still working after this PR is merged.

I don't know how this works either and wasn't able to find a way when quickly looking into that. I hope for @rkratky experience here.

doc/reference/netplan-yaml.md

rkratky · 2024-10-30T09:30:44Z

I don't know how this works either and wasn't able to find a way when quickly looking into that. I hope for @rkratky experience here.

Just dropping in to mention I'm not ignoring this PR/discussion -- I just couldn't find the time for investigating these two weeks. I hope to get back to normal next week.

davidekete and others added 3 commits September 24, 2024 16:17

docs: Fix docs directory structure to reflect Diátaxis

f038e81

Meson and docs-validation updates to reflect new docs dir structure.

196c0b0

Merge pull request #1 from rkratky/meson-updates

6890664

Meson and docs-validation updates to reflect new docs dir structure.

slyon added community This PR has been proposed by somebody outside of the Netplan team and roadmap commitments. documentation Documentation improvements. labels Sep 25, 2024

Fix paths to reference docs for link and spellcheck.

55c6895

Merge pull request #3 from rkratky/dir-fixes

c9625bc

Fix paths to reference docs for link and spellcheck.

slyon self-requested a review September 25, 2024 14:24

davidekete added 3 commits September 25, 2024 18:55

docs: Rename main files to index.md

5edc88e

docs: fix broken links

ab9d501

Merge branch 'Fix-docs-directory-structure-to-reflect-Diátaxis' of ht…

ddbe05c

…tps://github.com/davidekete/netplan into Fix-docs-directory-structure-to-reflect-Diátaxis

docs: add redirects

bef42bc

slyon requested changes Oct 9, 2024

View reviewed changes

davidekete added 3 commits October 20, 2024 01:14

docs: fix slyons comments

37f602e

docs: fix conflict

274cdde

Merge branch 'main' of https://github.com/davidekete/netplan into Fix…

7a67884

…-docs-directory-structure-to-reflect-Diátaxis

fix: revert redirect

09796a0

slyon requested changes Oct 23, 2024

View reviewed changes

doc/reference/netplan-yaml.md Show resolved Hide resolved

davidekete and others added 2 commits October 25, 2024 01:10

add redirects

74a7404

doc:conf: Make top-level redirects relative

c5c732b

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix docs directory structure to reflect diátaxis #520

Fix docs directory structure to reflect diátaxis #520

davidekete commented Sep 24, 2024 •

edited by rkratky

Loading

rkratky commented Sep 25, 2024 •

edited

Loading

davidekete commented Sep 25, 2024

rkratky commented Sep 25, 2024

slyon commented Sep 25, 2024

davidekete commented Sep 25, 2024

rkratky commented Oct 4, 2024

slyon left a comment

slyon Oct 9, 2024

davidekete Oct 20, 2024

rkratky commented Oct 10, 2024

slyon commented Oct 14, 2024 •

edited

Loading

rkratky commented Oct 15, 2024

davidekete commented Oct 15, 2024

slyon commented Oct 16, 2024

davidekete commented Oct 20, 2024

slyon left a comment •

edited

Loading

rkratky commented Oct 30, 2024

Fix docs directory structure to reflect diátaxis #520

Are you sure you want to change the base?

Fix docs directory structure to reflect diátaxis #520

Conversation

davidekete commented Sep 24, 2024 • edited by rkratky Loading

Description

Checklist

rkratky commented Sep 25, 2024 • edited Loading

davidekete commented Sep 25, 2024

rkratky commented Sep 25, 2024

slyon commented Sep 25, 2024

davidekete commented Sep 25, 2024

rkratky commented Oct 4, 2024

slyon left a comment

Choose a reason for hiding this comment

slyon Oct 9, 2024

Choose a reason for hiding this comment

davidekete Oct 20, 2024

Choose a reason for hiding this comment

rkratky commented Oct 10, 2024

slyon commented Oct 14, 2024 • edited Loading

rkratky commented Oct 15, 2024

davidekete commented Oct 15, 2024

slyon commented Oct 16, 2024

davidekete commented Oct 20, 2024

slyon left a comment • edited Loading

Choose a reason for hiding this comment

rkratky commented Oct 30, 2024

davidekete commented Sep 24, 2024 •

edited by rkratky

Loading

rkratky commented Sep 25, 2024 •

edited

Loading

slyon commented Oct 14, 2024 •

edited

Loading

slyon left a comment •

edited

Loading