Export of readme markdown generators as part of Stencil Core Compiler API

[legaev-stas]

Stencil version:

 @stencil/core@2.4.0

I'm submitting a:

[ ] bug report [x ] feature request [ ] support request => Please do not submit support requests here, use one of these channels: https://stencil-worldwide.herokuapp.com/ or https://forum.ionicframework.com/

Current behavior: Stencil generates a great API documentation. But if the default generator does not satisfy business needs, the consumers could generate custom documentation out of JsonDocs sources. But in this case the consumer has to create it from the scratches, while in some business cases the consumer might want to customize only some parts of default document.

Example: I need to modify default document generation process in the following way:

• to export all CSS Custom Props from all of the recursive dependencies. So that, parental element lists all nested customizable CSS props
• to add additional Interfaces section

Both of my changes do not modify existing markdown generators. These features only require data modification and creation of new Interface markdown generator + document template modification. I don't have any option how to re-use default markdown generators except copy their sources and their dependencies.

Expected behavior: Stencil exports markdown generators. They possibly could be exported as part of Stencil Core Compiler API. It could be exported as single apiDocsGenerationUtils object that has references to all of the generators.

With this feature consumers who want to implement partial redesign of default document generation process could reuse default markdown generators like this:

import {apiDocsGenerationUtils} from '@stencil/core/compiler';

const {
  stylesToMarkdown,
  eventsToMarkdown,
  methodsToMarkdown,
  partsToMarkdown,
  propsToMarkdown,
  slotsToMarkdown,
  usageToMarkdown,
} = apiDocsGenerationUtils;

Proposed Solution https://github.com/ionic-team/stencil/pull/2842

Thanks for considering implementation of requested feature!

[jordan-boyer]

This feature would really be great.

For example I really want to add example of my stencil composent using framework (vue, react).

I like the default formatter but i don't really want to write all the docs for the major framework, and I know it's possible with the custom doc but I don't want to copy paste your code for generating some part of the docs that I like

[beckysolomon]

This feature would be so helpful. I want to output usage and more robust documentation for methods, but I don't want to start from scratch. Would be nice to base it off the current default behavior and then customize from there.

[rwaskiewicz]

Hey folks 👋

I apologize that it took someone on the team so long to reply to this issue.

I discussed this with the team last night, and have agreed we'd rather pursue a different way of going about this. At this time, we feel that the various *ToMarkdown functions are best kept internal to Stencil.

However, we do wonder if there is a better compromise somewhere between creating a custom generator and copying the existing *ToMarkdown functions. Would adding an override of existing markdown generators solve the use case here? With a theoretical override functionality, projects could (in theory):

1. opt-out of sections of the docs they don't want to include
2. override sections that they would like to alter (as opposed to using Stencil's default functionality)
3. fall back to Stencil's documentation functionality if desired

For example, a configuration file for such an API might look something like:

// stencil.config.ts
{
    type: 'docs-readme',
    overrides: {
         methods: null, // do not include @Method documentation
         props: (metadata) => { }, // a custom implementation for displaying @Prop data
         // styles, events, parts, etc. (anything not specified above) will fall back to
        //      the default Stencil implementation
    }
}

Let us know what you think - thanks!

[legaev-stas]

Thank you for looking at the issue!

I think the solution you described would be very helpful for those who wants partially customizes docs generation process.