AlaskaAirlines / WC-Generator

Auro's automated web component generator
https://auro.alaskaair.com/getting-started/developers/generator/install
Apache License 2.0
5 stars 9 forks source link

Allow for customization of install content with markdown magic docs #322

Closed blackfalcon closed 2 weeks ago

blackfalcon commented 2 years ago

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

The current setup is the following.

  1. With a build, the README file is generated from a template loaded into docTemplates/README.md that is pulled from https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/README.md
  2. Within this template pulled from the remote on build, inner content for Install is pulled from https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/componentInstall.md

Because of this architecture, there is no way for a developer to customize any of the content around installation per an individual repo.

Describe the solution you'd like

Add a peerDependcies.md file that is referenced in the ./README.md template.

Exit criteria

This issue will be considered complete once there is a defined process for adding peer dependencies to the install documentation.

jason-capsule42 commented 2 years ago

The latest template has a custom section that is specifically there so that any custom non-standard information may be inserted into the readme.

Editing the file linked below will result in that content being inserted into the generated readme.

https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/template/docs/partials/readmeAddlInfo.md

geoffrich commented 2 years ago

Can you give an example of what you want to customize about the README that you are unable to do with the current setup?

blackfalcon commented 2 years ago

Moving to a model where there are peer dependencies that need to be installed with the primary element. See the recently released https://auro.alaskaair.com/components/auro/select/install instructions.

I am unable to edit the area under INSTALL, so I was forced to create an additional install instruction to alert the user of the additional peer deoendencies.

jason-capsule42 commented 2 years ago

The original template was created before we started down the path of documenting peer dependencies in this way.

I want to keep the readme template common between components and expose areas for optional additional information like what was done with readmeAddlInfo.md file. This gives us the ability to assert that all components will have a base template of parts that must be present and no component would be able to remove those sections.

I propose we add a peerDependcies.md file that is referenced in the readme.md template.

blackfalcon commented 2 years ago

I propose we add a peerDependcies.md file that is referenced in the readme.md template.

Ok, I can get on board with that. I will update the scope of this issue and exit criteria.