search

umco / umbraco-ditto

Ditto - the friendly view-model mapper for Umbraco
http://our.umbraco.org/projects/developer-tools/ditto
MIT License
79 stars 33 forks source link

API reference documentation #157

Closed leekelleher closed 8 years ago

leekelleher commented 8 years ago

Since we have such lovely XML comments through our code-base, should we look to auto-generate static API reference? Do we think this would be useful?

For my client work-projects, I've tried Sandcastle (SHFB) and Doxygen, both produce good results.

Yesterday I was told about DocFX, which is being used for new .NET Core docs, (and is supported by the .NET Foundation). I'd be interested in trying it out on Ditto.

We could wire it up with AppVeyor builds - pushing up the latest API ref docs to the GitHub release pages.

JimBobSquarePants commented 8 years ago

I made a poor man attempt at using DocFX with ImageProcesorCore but couldn't get it working. (I have an open issue for it https://github.com/JimBobSquarePants/ImageProcessor/issues/297).

I'm dying to give it a go. The Core docs are sweet! http://dotnet.github.io/api/index.html

leekelleher commented 8 years ago

On a side-note, I've been using (and contributing to) Wyam recently. It has a static code analysis module that can be used to generate API reference docs.

leekelleher commented 8 years ago

Quick update to say that I've started prototyping our docs using Wyam. I haven't pushed my local branch up yet, I'll see how I progress over the next few days.

My biggest concern is the front-end dev, CSS, etc. I'm tempted to do it in vanilla HTML and let you guys work your magic! :wink:

mattbrailsford commented 8 years ago

Something like this do?

capture

leekelleher commented 8 years ago

@mattbrailsford Nice!!

mattbrailsford commented 8 years ago

Had a look at the docs with a view to coming up with a better structure. What do we think of the following:

Comments?

leekelleher commented 8 years ago

Closing this issue off, any discussion can carry on over in PR #170