add minimal readme to npm packages with rst readmes

[brian-smith-tcril]

Currently, repos with rst readmes that are published to npm appear without a readme

https://www.npmjs.com/package/@edx/frontend-build

Since NPM doesn't support RST, we should use Markdown READMEs in those repositories. See this documentation decision for more details on why.

Once openedx/openedx-atlas#39 is resolved we will have a pattern to follow for other repos that have this issue.

Tasks

• For all repos that publish to NPM, convert their READMEs to Markdown
• For all MFEs that will be published to NPM, convert their READMEs to Markdown

Relevant Repos

Note: This list might need to be refreshed if the time between this being written and it being picked up is more than a few weeks.

Currently Published to NPM

Preview Give feedback

1. @edx/frontend-component-header
2. @edx/frontend-logging
3. @edx/frontend-analytics
4. @edx/frontend-enterprise
5. @edx/edx-bootstrap
6. @edx/edx-proctoring
7. @edx/frontend-component-site-footer
8. @edx/frontend-build
9. @edx/frontend-component-header-edx
10. @edx/frontend-auth
11. @edx/frontend-component-site-header
12. @edx/frontend-i18n
13. @edx/frontend-enterprise-catalog-search

MFEs that will be published in the Future

Preview Give feedback

1. frontend-template-application
2. frontend-app-authn
3. frontend-app-course-authoring
4. frontend-app-ora
5. frontend-app-library-authoring
6. frontend-app-accounthttps://github.com/openedx
7. frontend-app-discussions
8. frontend-app-ecommerce
9. frontend-app-payment
10. frontend-app-learning
11. frontend-app-enterprise-public-catalog
12. frontend-app-profile
13. frontend-component-footer
14. frontend-app-support-tools
15. frontend-app-learner-record
16. frontend-app-communications
17. frontend-app-ora-grading

Acceptance Criteria

• The READMEs for all MFEs and repos currently published to NPM are in Markdown format.
• All currently published packages have be re-published so that the new READMEs are visible on npmjs.org.

[OmarIthawi]

Copying my comment from openedx/openedx-atlas#39.

@brian-smith-tcril Based on my quick research, it looks like that npm doesn't support RST at all, while PyPi appears to support both RST and Markdown:

• https://docs.npmjs.com/about-package-readme-files
• https://packaging.python.org/en/latest/guides/making-a-pypi-friendly-readme/

Popular packages such as React.js use Markdown: https://www.npmjs.com/package/react

Some Open edX packages uses Markdown as well such https://www.npmjs.com/package/@edx/paragon while others don't as you pointed out for frontend-build.

We have a couple of options:

1. Use Markdown on all Open edX Nodej.s packages
2. Use Placeholder README (my least favorite)
3. Convert to Markdown on the fly (adds yet one more build step)

I'm leaning towards using Markdown at least until npmjs has support for RST.

I understand that RST is generally more powerful and concise (while Markdown can be flaky sometimes). However, it's helpful to see the full README within npmjs.

If popular packages like React.js and paragon can get away with Markdown, I believe other npm-published packages can.

I remember a decision to push for RST documentation, which is a good format for Sphinx docs and python tools but it seems that npmjs decides to keep it unsupported so it seems to worth a double check.

[brian-smith-tcril]

I did a search for all npm packages in the @edx org

repo	markdown readme	rst readme
@edx/paragon	✔️	❌
@edx/studio-frontend	✔️	❌
@edx/new-relic-source-map-webpack-plugin	✔️	❌
@edx/gradebook	✔️	❌
@edx/frontend-app-gradebook	✔️	❌
@edx/eslint-config	✔️	❌
@edx/frontend-lib-content-components	✔️	❌
@edx/frontend-component-header	❌	✔️
@edx/frontend-logging	❌	✔️
@edx/frontend-analytics	❌	✔️
@edx/frontend-enterprise	❌	✔️
@edx/edx-bootstrap	❌	✔️
@edx/edx-proctoring	❌	✔️
@edx/frontend-component-site-footer	❌	✔️
@edx/frontend-build	❌	✔️
@edx/frontend-component-header-edx	❌	✔️
@edx/frontend-auth	❌	✔️
@edx/frontend-component-site-header	❌	✔️
@edx/frontend-i18n	❌	✔️
@edx/frontend-enterprise-catalog-search	❌	✔️

I also know we plan to publish MFEs on npm, which would require moving those over to md too

repo	markdown readme	rst readme
frontend-app-learner-dashboard	✔️	❌
frontend-app-learner-portal-enterprise	✔️	❌
frontend-app-publisher	✔️	❌
frontend-app-admin-portal	✔️	❌
frontend-app-gradebook	✔️	❌
frontend-app-program-console	✔️	❌
frontend-app-learner-portal-programs	✔️	❌
frontend-app-shell	✔️	❌
frontend-app-programs-dashboard	✔️	❌
frontend-app-authn	❌	✔️
frontend-app-course-authoring	❌	✔️
frontend-app-ora	❌	✔️
frontend-app-library-authoring	❌	✔️
frontend-app-account	❌	✔️
frontend-app-discussions	❌	✔️
frontend-app-ecommerce	❌	✔️
frontend-app-payment	❌	✔️
frontend-app-learning	❌	✔️
frontend-app-enterprise-public-catalog	❌	✔️
frontend-app-profile	❌	✔️
frontend-component-footer	❌	✔️
frontend-template-application	❌	✔️
frontend-app-support-tools	❌	✔️
frontend-app-learner-record	❌	✔️
frontend-app-communications	❌	✔️
frontend-app-ora-grading	❌	✔️

based on this, it seems moving to md is non-trivial but not impossible