nixpkgs-review result

Generated using nixpkgs-review.

Command: nixpkgs-review pr 400816

x86_64-linux

I fail to understand how this is fixing the original issue, care to elaborate a bit more?

So this derivation, in its current state, will not work, as it is generated with nixos-render-docs with the index.html final positional argument, which generates the HTML under index.html. This also makes the inner anchor links generate under index.html.

If you pass in manual.html to nixos-render-docs, you get an error, as doc/redirects.json have not been updated yet with manual.html (they still reference index.html), so the builder fails with:

       >     If you moved content, add its new location as the first element of the redirects mapping.
       >     Please update doc/redirects.json or nixos/doc/manual/redirects.json!

The solution that was found to this "problem" was to move index.html to manual.html after generating it, which obviously breaks the derivation because this does not update the inner anchor links, who still reference index.html.

We have two options here (I went with 1):

1. Keep the manual generation under index.html
2. Generate the manual under manual.html, and also update doc/redirects.json

Considering nixpkgs-manual is meant to either be hosted on a server or accessed locally, I think it makes sense to keep it under index.html as it's a single page website.

But why would one use manual.html? What are the reason(s) we use it?

After looking at the blames for doc/doc-support/package.nix, I think I understand it more now.

This is where it originally was, and actually used common.indexPath for the move location. What should have been done from the beginning is generate the documentation directly under common.indexPath instead of moving the file, as that would take care of the anchor links. In essence, the manual would never work if one were to move the html file as that will break the anchors.

It was then hard coded in, in this specific commit.

@philiptaron any reason why you decided to rename the manual html file? I'm trying to understand the motivation behind it.

Nevermind, I read those commits wrong. It seems like it was always manual.html to begin with, and the derivation was just not generated there, causing the issues. This is what common.indexPath used to be set to.

The question would be now, do we want it named manual.html? I can't find where this specific derivation is being used within nixpkgs, so I'd assume naming it index.html wouldn't change a lot..?

EDIT: The redirects.json still mention index.html in master (and have been for a while), so that leads me to believe manual.html was never supposed to be.

Yeah, I tried to keep everything the same. redirects.json came about after my changes to refactor the derivation(s) so I don't know why they use index.html.

I do buy this change. I note that the production site manual.html is nowhere to be seen and index.html rules the day.

@fricklerhandwerk / @NixOS/documentation-team do you all have any idea about how this derivation makes it way to that site?

I plan on merging this and seeing what the fallout is. I expect there to be nothing.

We should be good now. Let me know if I missed anything.

Done. Please keep in mind that since we copied index.html to manual.html, the references to the anchor links will not reference the same file and will trigger a page reload when using the latter.

Thanks for your patience, everyone :)