search

dotnet / try

Try .NET provides developers and content authors with tools to create interactive experiences.
MIT License
2.89k stars 522 forks source link

Generated documentation + try.net #297

Open jakubsuchybio opened 5 years ago

jakubsuchybio commented 5 years ago

Is your feature request related to a problem? Please describe. No

Describe the solution you'd like I would like for try.NET to be "GOTO" software for generating documentation and creating custom/extending pages of generated documentation with examples. You already have docs.microsoft.com, what if you open-sourced the software that is generating them (with ability to contribute on GitHub) and then merge it with try.NET so that the examples in that generated documentation would "come alive"? I think that this would be something everybody would want. Yes we have doxygen and docfx. I tried doxygen, it doesn't look good or great... But if you would have OSS solution of docs.microsoft.com for everybody to generate docs from code + modifications by hand it would be game changer.

Describe alternatives you've considered Combining docfx and try.NET somehow. Haven't tried to do that yet, but maybe it is possible.

rjgotten commented 5 years ago

Yes we have doxygen and docfx. I tried doxygen, it doesn't look good or great... But if you would have OSS solution of docs.microsoft.com

Iirc Microsoft is dog-fooding a (modified / extended) version of DocFX to build documentation published on docs.microsoft.com.

If any integration is supposed to happen, then imho the ideal way to go would be to have the interactive sample capabilities of try.NET be surfaced as an extension to DocFX's code snippet notation.

agarcialeon commented 5 years ago

I have a related question to the issue. Since try,net uses markdown and Blazor. It's there support in github pages to host try.net generated markdown pages?

This way could be possible to generate documentation that mixes the API, static markdown pages with other information like interactive examples and make a fiddle for users.

rjgotten commented 5 years ago

@agarcialeon Is the runtime footprint for Blazor already small enough to facilitate easy download for hosted documentation on the public internet, then? I recall hearing that it was still quite large. Multiple megabytes.