From 088eab4aff3b8568cc863195bf545740a8be92c2 Mon Sep 17 00:00:00 2001 From: Peter Kulko <93188219+PKulkoRaccoonGang@users.noreply.github.com> Date: Fri, 2 Jun 2023 11:53:10 +0300 Subject: [PATCH] docs: created a Tools section on the documentation site (#2336) * docs: created a Tools section/page on the documentation site * refactor: code refactoring * refactor: refactoring after review --- www/src/components/Menu.scss | 2 +- www/src/components/Menu.tsx | 42 ++++---- www/src/pages/insights.tsx | 3 +- www/src/pages/tools/component-generator.mdx | 108 ++++++++++++++++++++ 4 files changed, 129 insertions(+), 26 deletions(-) create mode 100644 www/src/pages/tools/component-generator.mdx diff --git a/www/src/components/Menu.scss b/www/src/components/Menu.scss index ec00dd83d6..1b7830e834 100644 --- a/www/src/components/Menu.scss +++ b/www/src/components/Menu.scss @@ -40,7 +40,7 @@ } &-items { - margin-bottom: 3.75rem; + margin-bottom: $spacer; .pgn_collapsible { font-size: $font-size-xs; diff --git a/www/src/components/Menu.tsx b/www/src/components/Menu.tsx index ded59b2a92..ccd6084733 100644 --- a/www/src/components/Menu.tsx +++ b/www/src/components/Menu.tsx @@ -197,9 +197,6 @@ function Menu() { Contributing -
  • - Usage insights -
    • + + + {categories.map(({ fieldValue, nodes }) => ( -
    -

    - Playground - - Beta - -

    -
      -
    • - A UI builder for prototyping with Paragon components. - - Visit playground - -
      • -
    -
    { if (value !== tab) { global.analytics.track(`openedx.paragon.docs.insights.tabs.${value.toLowerCase().trim()}.clicked`); - navigate(INSIGHTS_PAGES.find(item => item.tab === value)!.path); + navigate(INSIGHTS_PAGES.find(item => item.tab === value).path); } }; - return ( diff --git a/www/src/pages/tools/component-generator.mdx b/www/src/pages/tools/component-generator.mdx new file mode 100644 index 0000000000..8248c47cdc --- /dev/null +++ b/www/src/pages/tools/component-generator.mdx @@ -0,0 +1,108 @@ +--- +title: Component generation +--- + +# Component generation + +Component generation offers pre-defined templates of the necessary files to kickstart development and automatically export the created components for use in the project. In this document, we will explore the process of component generation and the steps required to get started with this powerful feature. + +## 1. Start the documentation site development server + +The Paragon documentation site serves both as documentation and as a workbench to create your component within. To see your component in action, you need to run the documentation site locally. + +``` +npm install +npm start +``` + +## 2. Create new component + +To create new component run + +``` +npm run generate-component MyComponent +``` + +where `MyComponent` is your new component's name. + +This will create a directory in `/src/` that will contain templates for all necessary files to start developing the component: +``` +MyComponent +├── index.jsx +├── README.md +├── MyComponent.scss +├── _variables.scss +└── MyComponent.test.jsx +``` + +The script will also automatically export your component from Paragon. + +## 3. Start developing + +`/src/MyComponent/index.jsx` is where your component lives, the file is created with the following template, edit it to implement your own component. + +``` jsx +import React from 'react'; +import PropTypes from 'prop-types'; +import classNames from 'classnames'; + +const MyComponent = React.forwardRef(({ className, children }, ref) => ( +
    + {children} +
    +)); + +MyComponent.defaultProps = { + className: undefined, +}; + +MyComponent.propTypes = { + /** A class name to append to the base element. */ + className: PropTypes.string, + /** Specifies contents of the component. */ + children: PropTypes.node.isRequired, +}; + +export default MyComponent; + +``` + +## 4. (Optional) Add styles to your component. + +If your component requires additional styling (which most likely is the case), edit created SCSS style sheet in your +component's directory `/src/MyComponent/MyComponent.scss` which by default contains an empty class for your component. + +If you wish to use SASS variables (which is the preferred way of styling the components since values can be +easily overridden and customized by the consumers of Paragon), add them in `/src/MyComponent/_variables.scss` (this file should contain all variables specific to your component). +This way the variables will also get automatically picked up by documentation site and displayed on your component's page. + +**Please note that you need to follow [Paragon's CSS styling conventions](https://github.com/openedx/paragon/blob/master/docs/decisions/0012-css-styling-conventions).** + +## 5. Document your component + +The documentation for your component lives in `src/MyComponent/README.md`. The documentation site scans this directory for markdown or mdx files to create pages. By default, the file is created with following content: + +```` md +--- +title: 'MyComponent' +type: 'component' +components: +- MyComponent +status: 'New' +designStatus: 'Done' +devStatus: 'Done' +notes: | + Something special about this component +--- + +Describe your component here and give usage examples. + +### Basic Usage + +```jsx live + + Hello! + +``` + +````