Open brian-smith-tcril opened 10 months ago
Copying my comment from https://github.com/openedx/openedx-atlas/issues/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:
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:
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.
I did a search for all npm packages in the @edx
org
repo | markdown readme | rst readme |
---|---|---|
@edx/paragon | :heavy_check_mark: | :x: |
@edx/studio-frontend | :heavy_check_mark: | :x: |
@edx/new-relic-source-map-webpack-plugin | :heavy_check_mark: | :x: |
@edx/gradebook | :heavy_check_mark: | :x: |
@edx/frontend-app-gradebook | :heavy_check_mark: | :x: |
@edx/eslint-config | :heavy_check_mark: | :x: |
@edx/frontend-lib-content-components | :heavy_check_mark: | :x: |
@edx/frontend-component-header | :x: | :heavy_check_mark: |
@edx/frontend-logging | :x: | :heavy_check_mark: |
@edx/frontend-analytics | :x: | :heavy_check_mark: |
@edx/frontend-enterprise | :x: | :heavy_check_mark: |
@edx/edx-bootstrap | :x: | :heavy_check_mark: |
@edx/edx-proctoring | :x: | :heavy_check_mark: |
@edx/frontend-component-site-footer | :x: | :heavy_check_mark: |
@edx/frontend-build | :x: | :heavy_check_mark: |
@edx/frontend-component-header-edx | :x: | :heavy_check_mark: |
@edx/frontend-auth | :x: | :heavy_check_mark: |
@edx/frontend-component-site-header | :x: | :heavy_check_mark: |
@edx/frontend-i18n | :x: | :heavy_check_mark: |
@edx/frontend-enterprise-catalog-search | :x: | :heavy_check_mark: |
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 | :heavy_check_mark: | :x: |
frontend-app-learner-portal-enterprise | :heavy_check_mark: | :x: |
frontend-app-publisher | :heavy_check_mark: | :x: |
frontend-app-admin-portal | :heavy_check_mark: | :x: |
frontend-app-gradebook | :heavy_check_mark: | :x: |
frontend-app-program-console | :heavy_check_mark: | :x: |
frontend-app-learner-portal-programs | :heavy_check_mark: | :x: |
frontend-app-shell | :heavy_check_mark: | :x: |
frontend-app-programs-dashboard | :heavy_check_mark: | :x: |
frontend-app-authn | :x: | :heavy_check_mark: |
frontend-app-course-authoring | :x: | :heavy_check_mark: |
frontend-app-ora | :x: | :heavy_check_mark: |
frontend-app-library-authoring | :x: | :heavy_check_mark: |
frontend-app-account | :x: | :heavy_check_mark: |
frontend-app-discussions | :x: | :heavy_check_mark: |
frontend-app-ecommerce | :x: | :heavy_check_mark: |
frontend-app-payment | :x: | :heavy_check_mark: |
frontend-app-learning | :x: | :heavy_check_mark: |
frontend-app-enterprise-public-catalog | :x: | :heavy_check_mark: |
frontend-app-profile | :x: | :heavy_check_mark: |
frontend-component-footer | :x: | :heavy_check_mark: |
frontend-template-application | :x: | :heavy_check_mark: |
frontend-app-support-tools | :x: | :heavy_check_mark: |
frontend-app-learner-record | :x: | :heavy_check_mark: |
frontend-app-communications | :x: | :heavy_check_mark: |
frontend-app-ora-grading | :x: | :heavy_check_mark: |
based on this, it seems moving to md is non-trivial but not impossible
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 https://github.com/openedx/openedx-atlas/issues/39 is resolved we will have a pattern to follow for other repos that have this issue.
Tasks
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.
Acceptance Criteria