"Edit this page" is broken

[AFOliveira]

"Edit this page" button in HTML view is broken

Steps to reproduce the behavior:
If you test https://riscv-software-src.github.io/riscv-unified-db/manual/html/isa/20240411/insts/amoadd.d.html
and click on this button

It leads to this page.
https://github.com/riscv-software-src/riscv-unified-db/edit/main/gen/manual/isa/20240411/antora/modules/insts/pages/amoadd.d.adoc

Happens in all pages. Is this because its taking to the generated source rather than the original?

[kbroch-rivosinc]

Yes, looks like there's a way to provide custom URLs https://docs.antora.org/antora/latest/playbook/content-edit-url/#edit-url-key otherwise we should probably just disable the link.

If that is possible then I imagine we'd want the following for the example you gave: https://github.com/riscv-software-src/riscv-unified-db/edit/main/arch/inst/A/amoadd.d.yaml

[AFOliveira]

Thanks @kbroch-rivosinc, that seems exactly the solution we need!

[AFOliveira]

After revisiting this, I realize there isn’t an obvious solution, as converting the .adoc link back to the original .yaml file is inherently complex. That said, I see three potential approaches to address the issue:

1. Disable the link entirely: This removes the functionality but simplifies the problem.
2. Set a hardcoded reference to the arch/ folder: This would make it relatively straightforward for users to locate the relevant file to edit.
3. Implement a switch-case mechanism: This would guide users to a more specific folder within arch/ (e.g., arch/inst or arch/csrs) based on the content type, narrowing down their search for the correct file.

I lean towards the second approach because it preserves the purpose of the button and facilitates contributions. While the third option could offer more guidance, I don't see significant value in pre-selecting a folder for users. Once they’re directed to the arch/ folder, it should be reasonably simple to identify the appropriate file.

@kbroch-rivosinc @dhower-qc what do you think about this?

[kbroch-rivosinc]

From that list of options, I would also pick 2.

I thought of a possible 4th option:

4. Link to creating an issue. Could use existing provided path embedded in the URL. Example

This wouldn't preclude people from fixing the problem, but might allow people that wouldn't create a PR to at least report a potential problem. (Our response could be "Please submit a PR")

And actually we could probably do both?

[AFOliveira]

Agree, linking to the issue is also a great solution. Might even be better since it's a smaller step.

And actually we could probably do both?

Although, I don't think I fully comprehend what you mean here, is it having two buttons?

[kbroch-rivosinc]

And actually we could probably do both?

Never mind, there's only one edit_url in the config. So, I would vote to provide the "file an issue" link.

[dhower-qc]

I'd vote for removing the link entirely. I'm thinking we can have fine-grained links at the appropriate places ("edit this prose", "edit this IDL", ...) rather than a catch-all.

[AFOliveira]

I'd vote for removing the link entirely. I'm thinking we can have fine-grained links at the appropriate places ("edit this prose", "edit this IDL", ...) rather than a catch-all.

I think that would be the best, but I'm not sure if there how we can change it, I think probably we would need to change antora source, so in the meantime we would be left without any easy link from the content to the code. I agree that future wise, you approach is the best, but for ow do we want to have no button or a broken link?

Linking to create an issue would be a temporary fix, we could even keep this issue open until further solution is done.