Fix docs directory structure to reflect diátaxis by davidekete · Pull Request #520 · canonical/netplan

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

 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?

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.

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 · 2024-12-11T18:04:15Z

Hi guys, just bumping this issue. I tried my hand at it and posted the issue on StackOverflow for help. Have you guys had any luck on your end? @rkratky @slyon

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

davidekete · 2025-03-09T15:26:17Z

Hi @rkratky, @slyon. I was able to work around the issue by Implementing a custom redirect template that:

Uses JavaScript to detect the fragment from the old URL (window.location.hash).
Appends the fragment to the new redirected URL before navigation.
Uses window.location.replace() to prevent intermediate redirects from appearing in browser history.
Includes a fallback for users without JavaScript.

Let me know if you run into any issues testing.

davidekete · 2025-06-26T15:49:02Z

Hi @slyon @rkratky bump

@davidekete

* Moves topic files to resp. sub-dirs * Updates docs validation and manpage building scripts * Adds internal redirects to keep all links functional Note: Most work on this done by @davidekete in PR canonical#520. Thanks!

rkratky · 2026-01-18T19:26:16Z

@davidekete, @slyon

I submitted #567, which implements these changes -- it was simpler to start a new PR to avoid conflicts after such a long time has passed.

Apologies for taking so criminally long with responding to this and finalizing it. All credit for the actual work goes to @davidekete. In the new PR, I only added internal redirects to handle all of the changes and added some minor updates.

I really don't have a good excuse for neglecting this for so long, and I'm truly sorry. Somehow, I just kept postponing the work, and then it got totally out of hand. Something always came up that seemed more pressing at the time. Again, my apologies.

......

I believe the new PR is good to be merged. I tested the redirects as I could, and I didn't find any case where it wouldn't work as expected.

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 suggested 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 suggested changes Oct 23, 2024

View reviewed changes

Comment thread doc/reference/netplan-yaml.md

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

add redirects

74a7404

doc:conf: Make top-level redirects relative

c5c732b

davidekete added 3 commits March 9, 2025 16:07

fix: preserve anchors on redirect

c1a3f8b

fix: revert makefile to default

6e95365

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

14772f9

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

davidekete requested a review from slyon March 9, 2025 15:20

rkratky mentioned this pull request Jan 18, 2026

Changes docs dir structure from flat to Diataxis-based #567

Open

2 tasks

Conversation

davidekete commented Sep 24, 2024 • edited by rkratky Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

rkratky commented Sep 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidekete commented Sep 25, 2024

Uh oh!

rkratky commented Sep 25, 2024

Uh oh!

slyon commented Sep 25, 2024

Uh oh!

davidekete commented Sep 25, 2024

Uh oh!

rkratky commented Oct 4, 2024

Uh oh!

slyon left a comment

Choose a reason for hiding this comment

Uh oh!

slyon Oct 9, 2024

Choose a reason for hiding this comment

Uh oh!

davidekete Oct 20, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rkratky commented Oct 10, 2024

Uh oh!

slyon commented Oct 14, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rkratky commented Oct 15, 2024

Uh oh!

davidekete commented Oct 15, 2024

Uh oh!

slyon commented Oct 16, 2024

Uh oh!

davidekete commented Oct 20, 2024

Uh oh!

slyon left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rkratky commented Oct 30, 2024

Uh oh!

davidekete commented Dec 11, 2024

Uh oh!

davidekete commented Mar 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidekete commented Jun 26, 2025

Uh oh!

rkratky commented Jan 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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

davidekete commented Mar 9, 2025 •

edited

Loading