Imagesharp: API docs

[JimBobSquarePants]

Update

Docs are available at:
https://sixlabors.github.io/docs/

---

Original Issue

_From @JimBobSquarePants on January 13, 2016 0:43_

I would like to create documentation like the following:

http://dotnet.github.io/

MS are using the library below but I can't seem to follow the instructions.

http://dotnet.github.io/docfx/

_Copied from original issue: JimBobSquarePants/ImageProcessor#297_

[JimBobSquarePants]

_From @robertjf on January 13, 2016 0:53_

@JimBobSquarePants I have a little spare time at the moment and can take a look at it - have had a look through the walkthroughs etc.

Have you started a project for this in Visual Studio yet? If so do you want to check it in and I'll start with that, or do you want me to start from scratch? And is your preference to use Visual Studio IDE or configure it under dnx instead?

[JimBobSquarePants]

Awesome! Thanks mate :+1:

I haven't started a project yet, I planned to set a docs folder and stick a web project in there to do it all so I could preview.

[JimBobSquarePants]

_From @priyanshu92 on May 5, 2016 15:42_

@JimBobSquarePants I looked at it and created a sample documentation following their tutorials and I was able to create it but it doesn't seem to work on .NET Core projects :confused: with project extension as **.xproj. I think currently it only supports .csproj files. :disappointed:

Let me know if I can help.

[JimBobSquarePants]

@priyanshu92 Thanks for giving it a go, I had issues myself when I tried. Maybe I should look elsewhere for something to use.

Ideally I want something people can make pull requests against. I just wish Jekyll wasn't such a chore on Windows machines.

[M-Zuber]

Volunteering to try and kickstart this.

[JimBobSquarePants]

You're on! 😄 That would be awesome!

If possible I would like to get them to build into a /docs/ folder so that I can host from github pages easily.

[daveaglick]

@M-Zuber Not sure you've been following along, but the Wyam docs recipe is almost done! I'm getting Cake up and running first, but the Recipe in general should be just about ready. I merged it into the develop branch last week and a release should be coming in 2-3 weeks.

[daveaglick]

[M-Zuber]

I didn't forget, RL has been very the last bit.
But it is in in my schedule for today :fingers-crossed:

[M-Zuber]

It seems that docfx does not yet support xproj/project.json 😢

[JimBobSquarePants]

Oh! I thought that was how the netcore docs were generated?

[M-Zuber]

I did some more digging, and I was using the wrong Nuget per this, but trying to install the referenced package fails with:
Unable to find a version of 'Microsoft.CodeAnalysis.Common' that is compatible with 'Microsoft.CodeAnalysis.CSharp 2.0.0 constraint: Microsoft.CodeAnalysis.Common (= 2.0.0)', 'Microsoft.CodeAnalysis.VisualBasic 2.0.0 constraint: Microsoft.CodeAnalysis.Common (>= 2.0.0)', 'Microsoft.CodeAnalysis.Workspaces.Common 2.0.0 constraint: Microsoft.CodeAnalysis.Common (= 2.0.0)'.
Going to try another hack of telling it to just use the *.cs files.

If not, then I'll be pulling down the dev branch of Wyam

[M-Zuber]

Got something working!
(Did it by telling docfx to look for all .cs files and not a project file)

Still some rough edges, but I will start smoothing them out. Will open a PR once things get a bit smoother for feedback.

[JimBobSquarePants]

YYYAAAAAAASSSSSSSSS!!!!!!

[M-Zuber]

So, how I have the site being generated.
No idea if it is catching all the methods or not.
Just make a pr adding the project w/o the generated files, and they get generated by adding something in CI config?

[M-Zuber]

This is an interesting approach
They are using multiple repos, some for source code, one for the docs, and yet another to actually host the docs.
Which is crazy for this use case, but that script can probably be hacked on for our needs.

[JimBobSquarePants]

Aye... That's a bit mental. Github pages can be served from a /docs/ folder in the master repo so we should be able to build it in there much easier.

[M-Zuber]

So I am not quite sure which files need to be included in the pr, if any.
options:
1) nothing, just an empty web project with the docfx.msbuild nuget and accompanying docfx.json file
2) above + the generated yaml files
3) above + the generated html files

Thoughts?

[dlemstra]

I personally think that we should create a new repo (e.g. ImageSharp.Docs (too bad that google owns this TLD)) and store the docs there. Doing so will keep the history of this project clean and keep it a bit smaller.

[M-Zuber]

Its harder to keep in snyc though.
If we go with the first option I mentioned, there is almost nothing added to the size of the repo

[dlemstra]

Would it be possible to add examples that include images to the documentation? That will have a big impact on the size of the project. And we should only update the documentation when a new release has been published so keeping it in sync is probably not an issue.

[M-Zuber]

Yes, but having it in a seperate repo means a build step of cloning docs repo, running docfx, and pushing back up.
Simpler to just have it generated by build.
Images could be stored in another repo and served via github pages though

[JimBobSquarePants]

I could add an app to azure that serves any images perhaps

[M-Zuber]

Also a valid idea.
I'm away from the computer until Sunday, but available on the phone for another few hours.
Would love to reach a consensus so I can make the PR first thing Sunday

[JimBobSquarePants]

Apologies for the slow reply, birthday weekend....

I think we should go with adding this to the main repo. There's will be no images initially since it will be purely API docs. Anything additional custom images I can serve from Azure, another github pages repo, or somewhere else, as and when required.

Ideally I would serve the documentation from a /docs/ folder in the main repo. I will need to either preserve a CNAME file containing the domain http://imagesharp.net within that folder or recreate it on build.

https://support.dnsimple.com/articles/github-pages/#one-final-step

[M-Zuber]

Happy birthday again! and no worries.
apologies on my end if I sounding pressuring.

Anyways here you have the basis #22

[moshegutman]

What are your thoughts about using GitHub Pages for Tutorials/Sample code examples. This way people can easily edit them.

[M-Zuber]

The default docfx template includes a link on every page exactly for allowing people to quickly jump from the docs to making a pull request edit

[JimBobSquarePants]

Yeah, we just need to get the docs up and running. Hoping to have that for beta1