How can I specify languages for code examples? about widdershins HOT 9 CLOSED

@corvinusy there is a new option --environment or -e which allows you to load an options object from a file in yaml or json format at runtime without requiring a wrapper script. This should make it easier to override the language_tabs or any other options.

I've just released v2.2.0 including this enhancement.

Please feel free to re-open this issue if you encounter the output corruption bug again.

from widdershins.

Hi @corvinusy yes there's a couple of existing ways of doing this.

If you have x-code-samples specification extensions in your OpenAPI definition, you can use the --lang switch to enable automatic detection of the necessary language tab entries.

If you are using the programmatic API, you can specify in your options object that you want to override the default language-tabs.

E.g.

var converter = require('widdershins');
var options = {};
options.language_tabs = [{ 'http': 'HTTP' }, { 'javascript': 'JavaScript' }, { 'javascript--nodejs': 'Node.JS' }, { 'python': 'Python' }, { 'ruby': 'Ruby' }];
converter.convert(swaggerObj,options,function(err,str){
  //
});

This would only output the language-tabs specified (omitting shell and java). I have updated the README file to make this clearer.

If you need to do this from the command-line, I can see a potential way to do it, by allowing a config-file to be read to set the default options. Would this be of help?

Can I also ask whether you are using the npm package, or direct from git?

from widdershins.

I use npm package and run it in terminal as CLI-command.
I have generated openapi.json from other source language tool and want to create static *.md for project documentation.
I always tried to modify source code by removing items from language_tabs directly, but this lead to corrupted output.

Now I see how to do it with JS-wrapper script.
Thank you for fast reaction.

The issue can be closed if you don't want to see it as a reminder to update README or to provide some wrapper.

from widdershins.

Great. I'll leave the issue open for a while, in case you hit any snags (like corrupted output) when trying to override the language_tabs option. I've updated the README now, but the ability to read the options in from a config file might still be useful...

from widdershins.

If you need details about corrupted output: I removed all languages except shell, nodejs and python. And got not a properly closed sample tag (```) and end-braces. Seems nodejs sample generation has a dependency on pure javascript one.

Anyway, thank you for this good tool.

from widdershins.

Thanks for letting me know, I'll try it out a couple of ways and see if I can reproduce it.

from widdershins.

I've just realised the example above and in the README was wrong, you now need to pass a callback to the convert function, which takes an err and str parameters:

var converter = require('widdershins');
var options = {};
options.language_tabs = [{ 'http': 'HTTP' }, { 'javascript': 'JavaScript' }, { 'javascript--nodejs': 'Node.JS' }, { 'python': 'Python' }, { 'ruby': 'Ruby' }];
converter.convert(swaggerObj,options,function(err,str){
  // str contains the output markdown
});

from widdershins.

Hi. Is there a way I can get C# code through widdershins in my langugage tab?

from widdershins.

Hi, @areebaasad77 there's a number of ways to do it!

• Create a code_csharp.dot template and specify a --user_templates option
• Include x-code-samples extensions in your API definition and use the --lang option
• Use the --httpsnippet and --language-tabs options

All as per the help / README. If you did option 1 then you could contribute it back as a pull request.

Let me know if you need anything further.

from widdershins.