ex_doc icon indicating copy to clipboard operation
ex_doc copied to clipboard

Published 20 hours ago • verified publisher icon elixir-lang

Add "Edit Documentation" link

Open wojtekmach opened this issue 2 years ago • 7 comments

Extracted from https://github.com/elixir-lang/ex_doc/pull/1818#issuecomment-1822395188.

I think we have all the ingredients:

  1. GitHub code edit links may contain line numbers, notice the editor cursor is at line 3: https://github.com/elixir-lang/ex_doc/edit/main/lib/ex_doc/markdown.ex#L3

  2. Remix has a suitable icon: https://remixicon.com/icon/edit-line

Here is a mockup:

image

WDYT?

wojtekmach avatar Nov 23 '23 12:11 wojtekmach

Oh, the link is a bit problematic. It seems it has to point to a branch and not a tag. This link https://github.com/elixir-lang/ex_doc/edit/v0.30.9/lib/ex_doc/markdown.ex#L3 404s.

There are thus two problems:

  1. We need to add a configuration for a branch, we shouldn't just hardcode "main".
  2. The edit link will get out of sync as the branch moves forward.

wojtekmach avatar Nov 23 '23 12:11 wojtekmach

Nice!

We have used main/master in https://erlang.org/doc for the target and so far I have not received any complaints. Whenever anyone edits the docs, they really should be editing the latest as things may already have been fixed.

You could also add a "View Documentation Source" in addition to "View Source" and get rid of that problem.

garazdawi avatar Nov 23 '23 13:11 garazdawi

What would happen for non-GitHub hosted projects (I don't have any personally, but it would be worthwhile to consider how this might be configured both for enablement (some people may not want those links on their documentation) and target.

halostatue avatar Nov 23 '23 15:11 halostatue

Any update on this? I often want to jump to the GitHub page of a project and currently I have to open a new tab and search for the project on Google and then get to the GitHub page. Having a direct edit link would be such a nice convenience and would do wonders in improving my workflow.

yasoob avatar Feb 17 '24 00:02 yasoob

@yasoob the feature is already there for the source code. All you need to do is to click on the source icon and then the edit icon already on GitHub. It should take two clicks.

josevalim avatar Feb 17 '24 08:02 josevalim

That said, I believe we can close this one. With Erlang moving to -doc attributes, docs and source are also collocated there, which reduces the need for a new link.

josevalim avatar Feb 17 '24 08:02 josevalim

In Erlang the docs are however not always colocated with the code, but can be referred via -doc {file, …}. So from our perspective a view/edit doc button would be a nice addition.

garazdawi avatar Feb 17 '24 11:02 garazdawi

This has not seen any activity and it seems the usage of -doc {file, ...} is quite rare. We can reopen it if someone really needs it.

josevalim avatar Oct 20 '25 13:10 josevalim