Docfx: Question: supporting other (non .Net ) languages

[bfcamara]

Hi! Congrats. This tool is awesome that I'm wondering if its usage is limited to .Net languages (supporting now C# and VB.Net).

In my scenario I provide "C#/Typescript/Java Client libraries" to a REST API. So it would be great that I could use this tool to generate the whole site. A couple of questions:

1. How specific to .Net is the metadata specification format? Imagine that I use an external tool to generate the API metadata - how hard it would be to use the current spec with Typescript or even Java metadata?
2. Any plans to support other languages out of the box? Or any plans to support "metadata extractor" plugins in order to extract metadata for other languages (instead of using Roslyn)

Thanks in advance

[chenkennt]

Hi bfcamara,

.NET metadata format is specific to .NET languages, you can see .NET specific terms like namespace and assembly in the metadata file. But I guess in your scenario you can write a custom template to map them to similar concepts in other language since these languages have a lot in common.

If the .NET metadata format doesn't meet you need, DocFX actually allows you to create you own metadata format, but you'll need to write a plugin to define data model and process the metadata file on your own.

[bfcamara]

Hi @chenkennt

thanks for the clarification. A new plugin is an option that I'm considering. Although, I was trying to use the General Metadata Specification (with just items, references, uids, etc.) and not the .Net Metadata Specification, but I couldn't find a way to override the template for yml files. It seems that as soon as I have a yml file, the template applied is the ManagedReference template.

I managed to override the template to use in conceptual markdown files, by using a yml section with a property documentType like this

title: TypeScript API
documentType: tsmetadata
---
{
   ...Here goes the TypeScript Metadata
}

Im this case docfx will use the template tsmetadata.html.tmpl. The drawback here is that the ts metadata itself will be available in a conceptual property as a string (I could use the js transformation to parse the string as json and populate the model before applying the template).

But I couldn't find a way to specify a different template for yml files. In the end I can change the current ManagedReference template to handle Managed languages and other Non Managed languages but I would end with a lot of logic in my template to decide what and how to show items depending on the Metadata (TypeScript vs Java vs .Net) that the template is processing. That's why I am trying to use a mechanism to override the template to use based on something that is in the metadata itself.

[chenkennt]

Using documentType is the right way to specify template. But I'd recommend you to use plugin to set the value of documentType. Plugin can decide which files to process by looking at the file names (for example, ManagedReferenceDocumentProcessor), you can give your metadata file a special extension like .ts.yml to make it be processed by another plugin.

[evil-shrike]

+1 for TypeScript out-of-the-box support!

[Serivy]

+1

[magol]

+1 for C++

[vicancy]

Currently to support a new language, the following steps are required:

1. a new processor plugin to process the new language: http://dotnet.github.io/docfx/tutorial/howto_build_your_own_type_of_documentation_with_custom_plug-in.html
2. a new template for this new document type http://dotnet.github.io/docfx/tutorial/intro_template.html#naming-rule-for-a-renderer-file

Ideas to simplify the workflow:

1. schema based data model

[hellosnow]

We also have UniversalReferenceDocumentProcessor, try to fit your model inside the processor and test. @superyyrrzz

[Fuzzylog1cza]

From what I can see there hasn't been a lot of movement in supporting TypeScript. Has this idea been dropped or is it just a time thing?

[vicancy]

For supporting TypeScript,

• [x] 1. https://github.com/docascode/type2docfx to convert it to YAML
• [ ] 2. Add template to support it

[Fuzzylog1cza]

Thank you. I'll do some digging for a template or see about contributing one.

[rishu-samsung]

Has anyone tried creating DocFX based documentation for C?