Developer facing API documentation tool?
-
In the old days, I used to use Sandcastle to create dev facing browsable documentation (e.g. for an SDK). What would you recommend today? Thanks, /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
In the old days, I used to use Sandcastle to create dev facing browsable documentation (e.g. for an SDK). What would you recommend today? Thanks, /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
Depends on your environment I suppose. In the JavaScript/TypeScript world, [jsdoc](https://github.com/jsdoc/jsdoc) is the defacto standard. Even VS Code has built-in intellisense support for it too.
Jeremy Falcon
-
In the old days, I used to use Sandcastle to create dev facing browsable documentation (e.g. for an SDK). What would you recommend today? Thanks, /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
I've been hearing a lot about OpenAPI[^] but it feels like a lot of overhead. However, there may be some dev tools it is being built into. Here's the main quote about it:
from the link:
What is the OpenAPI Specification? The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.
-
Depends on your environment I suppose. In the JavaScript/TypeScript world, [jsdoc](https://github.com/jsdoc/jsdoc) is the defacto standard. Even VS Code has built-in intellisense support for it too.
Jeremy Falcon
Jeremy Falcon wrote:
Depends on your environment
Strictly C#. /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
Jeremy Falcon wrote:
Depends on your environment
Strictly C#. /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
You could always write one in [this](https://github.com/Folds/osmosian). Ducks and runs.
Jeremy Falcon
-
You could always write one in [this](https://github.com/Folds/osmosian). Ducks and runs.
Jeremy Falcon
You just had to bring that guy back up... X|
Asking questions is a skill CodeProject Forum Guidelines Google: C# How to debug code Seriously, go read these articles.
Dave Kreskowiak -
You just had to bring that guy back up... X|
Asking questions is a skill CodeProject Forum Guidelines Google: C# How to debug code Seriously, go read these articles.
Dave Kreskowiak:-O
Jeremy Falcon
-
In the old days, I used to use Sandcastle to create dev facing browsable documentation (e.g. for an SDK). What would you recommend today? Thanks, /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
Thanks, Rick. I also think I'm going to continue to stick with SHFB as it's actively supported. /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
Thanks, Rick. I also think I'm going to continue to stick with SHFB as it's actively supported. /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
Last year I posted an SHFB issue and Eric Woodruff (not family of "our" Woodruff) responded quickly. By then I had solved the issue by arranging the project in another way, but found his response very positive. :-\
-
Last year I posted an SHFB issue and Eric Woodruff (not family of "our" Woodruff) responded quickly. By then I had solved the issue by arranging the project in another way, but found his response very positive. :-\
Yes, EW is a good guy. /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
In the old days, I used to use Sandcastle to create dev facing browsable documentation (e.g. for an SDK). What would you recommend today? Thanks, /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
Sandcastle? Is that the system I remember from the days I was maintaining a toolbox installation wizard: The users wanted Sandbox included in a toolbox. It took ages to install the 115,000 files. It turned out that those asking for it only needed the core functionality, so the installation was reduced to no more than 60,000 files. I may be mixing it up with another tool in the same toolbox, but I believe it was Sandbox going completely bananas in number of files installed.
-
In light of your post above... So he doesn't have to write the non-existent references that ChatGPT will create?
Software rusts. Simon Stephenson, ca 1994. So does this signature. me, 2012
-
Sandcastle? Is that the system I remember from the days I was maintaining a toolbox installation wizard: The users wanted Sandbox included in a toolbox. It took ages to install the 115,000 files. It turned out that those asking for it only needed the core functionality, so the installation was reduced to no more than 60,000 files. I may be mixing it up with another tool in the same toolbox, but I believe it was Sandbox going completely bananas in number of files installed.
SandCastle is not the easiest tool, I agree, but the free alternatives that I tried were disappointing, most could not generate .chm help files. Sandcastle Help File Builder (SHFB) makes using SandCastle a lot simpler: GitHub - EWSoftware/SHFB: Sandcastle Help File Builder (SHFB)[^]
-
In the old days, I used to use Sandcastle to create dev facing browsable documentation (e.g. for an SDK). What would you recommend today? Thanks, /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
I would say Swagger/Swashbuckle for OpenAPI-style REST API's. You can add quite some additional info on top of an already developer-oriented API description, and it can be used to generate clients that will 'just work' based on the spec. For an SDK in the form of a nuget file, since you said you were doing C#, package a markdown readme file in the nuget, this way the documentation comes with the library. I prefer having version-bound and 'incorporated' documentation rather than having to go look for it on some site, that 9 out of 10 times is not updated to match your version. And eventually, depending on your requirements, a generated and organic documentation site using something like docfx might be useful to give some additional info, which again, can/should be linked to from within the nuget or Swagger.
-
In the old days, I used to use Sandcastle to create dev facing browsable documentation (e.g. for an SDK). What would you recommend today? Thanks, /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
Ill just recap what another said, and might not be useful as sounds like a program API, instead of web API. but yeah, OpenAPI Specification, formally Swagger, with Swashbuckle being the C# .net implementation, is a JSON formatted specification. Which has been levelled up to standard that other web api ingesting services have incorporated so no some automated level of point and click, and your program knows how all the details needed to use that web api service. Mention only, that maybe specification been branched out to cover other types of API
-
In the old days, I used to use Sandcastle to create dev facing browsable documentation (e.g. for an SDK). What would you recommend today? Thanks, /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
I have always used HelpSmith for all of documentation. It can produce CHM files along with printed output, online\HTML output, PDFs and Word documents. See... https://www.helpsmith.com/
Steve Naidamast Sr. Software Engineer Black Falcon Software, Inc. blackfalconsoftware@outlook.com
-
In the old days, I used to use Sandcastle to create dev facing browsable documentation (e.g. for an SDK). What would you recommend today? Thanks, /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
I had a requirement to produce documentation for a graduate class in Advanced Data Structures. The professor let us choose the language WA wanted to use, within reason. I choose C# and documented all the classes, methods, etc. using C#'s triple slash (///) syntax. I then used DocFX to produce the first pass at the doc web site. Spent some time understanding how to add additional content and spruce up the final product. Did all three projects with this technique. Was very satisfied with the result. Got a great grade, maybe because my programs were good, but I like to think the quality of the documentation site helped.
-
You could always write one in [this](https://github.com/Folds/osmosian). Ducks and runs.
Jeremy Falcon
oooooh! that is a thing of beauty :)
