Provide a link to the corrosponding GitHub file for API documentation?

[devlead]

@robertmuehsig commented on Mon Jul 11 2016

I hope this is the correct repository for documentation "issues" - this is more or less a suggestion or an idea.

I'm currently digging in CAKE and read the documentation, e.g. this:

http://cakebuild.net/api/cake.core.tooling/d75cd243/60ae911b

It would be very handy if there would be a big "Improve on GitHub" button which points directly to this file. This could improve the documentation and would help to understand the code better.

I'm not sure how the documentation is currently build - if you gave me some hints I could try to implement this "feature".

What do you think?

---

@gep13 commented on Mon Jul 11 2016

@robertmuehsig you will see that on some pages, i.e. this one:

http://cakebuild.net/docs

that we already have that. For this particular page that you are referring to, the documentation is generated directly from the XML comments within the source code of the file

While I agree with your comment that it would be nice to have this functionality, I am not sure if this is something that we want to tackle just now. I know @patriksvensson has some ideas about the current site, and how it is written/constructed, and this way well change.

---

@robertmuehsig commented on Mon Jul 11 2016

Ah - yeah - I noticed that some page have this functionality and others don't. If you think this would be valuable, just let me know and I try to help.

---

@gep13 commented on Mon Jul 11 2016

@robertmuehsig said... Ah - yeah - I noticed that some page have this functionality and others don't. If you think this would be valuable, just let me know and I try to help.

In general, we will accept any help that is offered with regard to the site. Neither @patriksvensson @devlead or myself have any sort of flair when it comes to web design :smile: I think that would need to be part of a larger conversation though, perhaps when @patriksvensson is back from holiday.

---

@devlead commented on Mon Jul 11 2016

I too would love to see this functionality :+1:

Issue is that the xml docs don't contain any file or line number information, we generate from the nuget using assembly and xml doc file for both Cake & Addin assemblies. Currently we'rent shipping any symbols either so we don't have any PDBs, also for it to fully work we and addin authors would need to use something like GitLink so we can link to the right repository, branch and version of each file.

So providing this functionality likely isn't impossible but do entail some yak shaving.

---

@gep13 commented on Mon Jul 11 2016

@devlead said.... So providing this functionality likely isn't impossible but do entail some yak shaving.

yak yak yak :smile:

---

@devlead commented on Mon Jul 11 2016

@gep13 said... yak yak yak :smile:

"We accept pull requests..." :wink:

---

@robertmuehsig commented on Mon Jul 11 2016

How do you generate those pages?

---

@devlead commented on Mon Jul 11 2016

@robertmuehsig it's currently dynamically generated when the website starts, it's all custom code mostly written by @patriksvensson .

[daveaglick]

Just a note that providing an edit link for generated API documentation is still troublesome (if not impossible) in the new static site. While I suppose it's possible to back out the original source file and prepend the appropriate GitHub path for the core Cake source, doing so for addins would prove challenging. The addin YAML data does tell us where the repo is, so it might be possible...

I'd file this under "stuff that would be cool but we won't get to anytime soon"

[devlead]

@daveaglick agree this is a (real) nice to have, wonder if using something like GitLink could help for nuget binaries? And enabling it only for those that do.