Fix docs directory structure to reflect diátaxis

[davidekete]

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.

[rkratky]

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

[davidekete]

@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]

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]

• 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

[davidekete]

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]

@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]

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?

[davidekete]

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

[rkratky]

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]

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]

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]

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]

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.

[davidekete]

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]

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.