Skip to content
This repository was archived by the owner on Mar 30, 2021. It is now read-only.

Commit 228a584

Browse files
sarthak-sehgalsarthak-sehgal
authored
Merge pull request #33 from Nikhil-Vats/update_documentation_for_new_features
Update documentation for new features
2 parents e4df4d1 + 9602f42 commit 228a584

File tree

2 files changed

+170
-52
lines changed

2 files changed

+170
-52
lines changed

‎CONTRIBUTING.md

Lines changed: 71 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,37 +11,37 @@ Step 1: Clone the repository.
1111

1212
a) Using HTTPS -
1313

14-
```bash
14+
```
1515
git clone https://github.com/biojs/generator-biojs-webcomponents.git
1616
```
1717

1818
b) Using SSH -
1919

20-
```bash
20+
```
2121
git clone [email protected]:biojs/generator-biojs-webcomponents.git
2222
```
2323

2424
Step 2: Go to generator's directory
2525

26-
```bash
26+
```
2727
cd generator-biojs-webcomponents
2828
```
2929

3030
Step 3: Install yeoman
3131

32-
```bash
32+
```
3333
npm install -g yo
3434
```
3535

3636
Step 4: Symlink the package
3737

38-
```bash
38+
```
3939
npm link
4040
```
4141

4242
Step 5: Go out of the generator's directory. Run and test the generator locally.
4343

44-
```bash
44+
```
4545
cd ..
4646
mkdir test-biojs-generator
4747
cd test-biojs-generator
@@ -50,6 +50,71 @@ yo biojs-webcomponents
5050

5151
Note: If you have installed the generator-biojs-webcomponents globally, there is no need to worry, this method will still work. You do not need to uninstall anything.
5252

53+
### About the project
54+
55+
The project directory has the following structure -
56+
57+
```bash
58+
├── __tests__
59+
│ └────── app.js
60+
├── .github
61+
│ └────── issue_template.md
62+
│ └────── pull_request_template.md
63+
├── generators
64+
│ └────── app
65+
│ └────── templates
66+
| | ├── dev
67+
| | │ └────── serve.js
68+
| | ├── examples
69+
| | │ └────── index.html
70+
| | ├── img
71+
| | │ └────── favicon.png
72+
| | ├── node_modules
73+
| | │ ├────── modules
74+
| | ├── src
75+
| | │ ├────── index.js
76+
| | │ └────── style.less
77+
| | ├── index.html
78+
| | ├── LICENSE
79+
| | ├── package.json
80+
| | ├── package-lock.json
81+
| | ├── README.md
82+
| | └── webpack.config.js
83+
| |
84+
│ └────── index.js
85+
│ └────── validator.js
86+
├── node_modules
87+
│ ├────── modules
88+
├── .editorconfig
89+
├── .eslintignore
90+
├── .gitattributes
91+
├── .gitignore
92+
├── .travis.yml
93+
├── .yo-rc.json
94+
├── .CONTRIBUTING.md
95+
├── LICENSE
96+
├── package-lock.json
97+
├── package.json
98+
└── README.md
99+
```
100+
101+
#### __tests__
102+
Contains the test file - app.js which has all the tests for the generator.
103+
104+
#### .github
105+
Contains templates for GitHub issues and pull requests, make sure to follow these when you submit an issue/PR.
106+
107+
#### generators
108+
Contains all the code for generator.
109+
110+
1. app/templates - Contains all the templates which are generated whenever any user runs the generator. Read the directory structure and the purpose of each folder inside the templates folder [here](README.md##ii-description-of-your-projects-folder-structure).
111+
112+
2. app/index.js - Contains all the initializing code, prompts, writing code which actually uses the [templates](generators/app/templates) to generate the web-component project and installs required dependencies.
113+
114+
3. app/validator.js - Contains the validator functions for the prompts which checks user inputs and also performs other functions like copying the build file, installing the component as npm package, downloading the build file from npm package and validating npm package's version.
115+
116+
All the other files are self explanatory.
117+
53118
### To-do / roadmap.
54119

55120
See [issues](issues) for more details - we still need the following:

‎README.md

Lines changed: 99 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -17,25 +17,38 @@ Note: If you need to manage multiple versions of node also consider [nvm](https:
1717

1818
Step 1: Install [Yeoman](http://yeoman.io).
1919

20-
```bash
20+
```
2121
npm install -g yo
2222
```
2323

2424
Step 2a: Install [generator-biojs-webcomponents](https://www.npmjs.com/package/@biojs/generator-biojs-webcomponents).
2525

26-
Note that below you can change my-new-component to the folder name of your choice. e.g. - your project name.
27-
28-
```bash
29-
mkdir my-new-component
30-
cd my-new-component
31-
npm install -g yo @biojs/generator-biojs-webcomponents
26+
```
27+
npm install -g yo @biojs/biojs-webcomponents
3228
```
3329

3430
Step 2b: Generate your new project.
3531

36-
```bash
37-
yo @biojs/biojs-webcomponents
3832
```
33+
i) yo @biojs/biojs-webcomponents
34+
```
35+
This will make a **new directory** named `web-component` in the **current directory**. The `web-component` directory will be your **project directory**. If there is already a directory with the name `web-component`, the generator will not make a new one, rather **the existing one will be your project directory**.
36+
37+
OR
38+
39+
```
40+
ii) yo @biojs/biojs-webcomponents .
41+
```
42+
This will run the generator in the **current directory**.
43+
44+
OR
45+
46+
```
47+
iii) yo @biojs/biojs-webcomponents /anyPath/yourNewProjectDir
48+
```
49+
This will run the generator in a new directory named `yourNewProjectDir` (you can choose any other name), the new directory will be created at the **path you specified**. If there is already a directory with the same name as you provided, the generator will not make a new one, rather **the existing one will be your project directory**.
50+
51+
3952

4053
After running this, you will be asked some questions about the details of your project, after which the required dependencies will be automatically installed. You can read more about the whole workflow and the questions asked [here](#iii-workflow-and-questions).
4154

@@ -45,7 +58,7 @@ and `examples/index.html` to get started - there are instructions in the code.
4558
## II. Description of your Project's Folder Structure
4659
Once you complete all the steps mentioned above you will have a project with a folder structure like this -
4760

48-
```bash
61+
```
4962
├── dev
5063
│ └────── serve.js
5164
├── examples
@@ -95,7 +108,9 @@ If you face any issue, feel free to contact us at [Gitter](https://gitter.im/bio
95108

96109
After running ```yo @biojs/biojs-webcomponents``` in your terminal, you will be asked -
97110

98-
```bash
111+
```
112+
? Press Enter key to get going!
113+
99114
? What do you want to do today?
100115
> Upgrade an existing component to a Web Component
101116
Make a new Web Component
@@ -107,86 +122,124 @@ Based on your choice, you will be asked different questions. Read more -
107122

108123
A) Import the build file of your existing component into the project's directory.
109124

110-
1) You can import the build file from your local computer.
111-
2) If you do not have the build file in your computer, you can import it from your component's package on npm.
125+
1) Install the component from npm [**Recommended - Fastest way**]
126+
2) You can import the build file from your local computer.
127+
3) If you do not have the build file in your computer, you can import it from your component's package on npm.
112128

113-
```bash
129+
```
114130
? We need the build file (generally index.js, main.js or componentName.js) for this,
115131
import it using one of the options -
116-
1) Tell us the path of the file on your local machine and we will import it in the project.
117-
2) Tell us the npm package name, version, etc. and we will import it.
132+
1) Install component from npm package (Recommended - fastest way)
133+
2) Tell us the path of the file on your local machine and we will import it in the project.
134+
3) Tell us the npm package name, version, etc. and we will import it.
118135
```
119136

120-
Import from your local machine -
137+
B1) Install component from npm package -
121138

122-
B) Enter the path of your build file.
139+
You have to enter the package name (case sensitive) of your component, the generator will show you the description of your package and ask whether the description shown is correct or not.
123140

124-
```bash
125-
Please enter the path of the build file.
141+
```
142+
Enter the package name (case sensitive).
143+
Press enter if the package description shown is correct.
126144
```
127145

128-
The generator will make a directory named ```component-dist``` in your component's directory. Your build file will be imported in this directory. If this directory (component-dist) already exists, you can enter ```skip``` and enter the path of the build file in the next question (given below).
146+
If the description shown is incorrect, press ```N``` and you will go back to step A where you can choose to enter the package name again or import the file from local storage.
129147

130-
```bash
131-
Please enter the path of the build file, we will paste it into the existing directory.
148+
```
149+
? What do you want to do?
150+
1) Enter package name again to install component from npm package. (Recommended - fastest way)
151+
2) Import the file locally from your computer.
152+
3) Enter package name, version, build file URL to download the build file.
153+
```
154+
155+
If the description shown is correct, press ```Enter``` or ```Y```. You will be asked about the version of the package you want to import from. You can press ```Enter``` if you want to import from the latest version or you can enter the version you need. If you enter a version which does not exist, the generator will ask for version again.
156+
157+
```
158+
Great! We will import the latest version of your file from the npm package, if you don't want this,
159+
enter the version.
132160
```
133161

134-
Import from your compnent's package on npm -
162+
Your component will be installed. Next, the questions in [this](#make-a-new-web-component) section will be asked.
135163

136-
C) You have to enter the package name (case sensitive) of your component, the generator will show you the description of your package and ask whether the description shown is correct or not.
164+
B2) Import build file from your local storage -
137165

138-
```bash
166+
Firstly, the generator will ask you about the build directory - the build file will be imported in this directory which will be created in your project directory. You can press ```Enter``` if you want the default name - ```component-dist``` or enter a name of your choice.
167+
168+
If a directory with the same name already exists in your project directory, you can either enter a new name for your directory or press ```o```/```O``` if you want to overwrite the content of existing directory.
169+
170+
```
171+
The build file will be imported in a separate directory in the project's root.
172+
Enter the name of this directory or press Enter if you like to go with default.
173+
(component-dist)
174+
```
175+
176+
Enter the path of your build file.
177+
178+
```
179+
Please enter the path of the build file.
180+
```
181+
182+
Your build file will be imported in the build directory. Next, the questions in [this](#make-a-new-web-component) section will be asked.
183+
184+
B3) Import build file from your compnent's package on npm -
185+
186+
You have to enter the package name (case sensitive) of your component, the generator will show you the description of your package and ask whether the description shown is correct or not.
187+
188+
```
139189
Enter the package name (case sensitive).
140190
Press enter if the package description shown is correct.
141191
```
142192

143193
If the description shown is incorrect, press ```N``` and you will go back to step A where you can choose to enter the package name again or import the file from local storage.
144194

145-
```bash
195+
```
146196
? What do you want to do?
147-
1) Enter package name again.
197+
1) Enter package name again to install component from npm package. (Recommended - fastest way)
148198
2) Import the file locally from your computer.
199+
3) Enter package name, version, build file URL to download the build file.
149200
```
150201

151-
If the description shown is correct, press ```Enter``` or ```Y```. You will be asked about the version of the package you want to import from.
202+
If the description shown is correct, press ```Enter``` or ```Y```. You will be asked about the version of the package you want to import from. You can press ```Enter``` if you want to import from the latest version or you can enter the version you need. If you enter a version which does not exist, the generator will ask for version again.
152203

153-
```bash
154-
Great! We will import the latest version of your file from the npm package, if you don't want this,
155-
enter the version.
204+
```
205+
Great! We will import the latest version of your file from the npm package,
206+
if you don't want this, enter the version.
156207
```
157208

158-
You can press ```Enter``` if you want to import from the latest version or you can enter the version you need. If the version exists, you will be shown a URL which will redirect you to your package's directory.
209+
Once you enter a valid version and press ```Enter```, the generator will ask you about the build directory - the build file will be imported in this directory which will be created in your project directory. You can press ```Enter``` if you want the default name - ```component-dist``` or enter a name of your choice.
159210

160-
```bash
161-
This URL - https://www.jsdelivr.com/package/npm/<your-package-name>?version=<your-package-version>
162-
contains the directory of the package, please find the build file (generally in the dist or build
163-
folder) and paste the link here, we will download it for you.
164-
```
211+
If a directory with the same name already exists in your project directory, you can either enter a new name for your directory or press ```o```/```O``` if you want to overwrite the content of existing directory.
165212

166-
After going to this URL, you can find the build file in the root folder or a separate folder named build or dist. The build file is generally named index.js, package_name.js, index.min.js or package_name.min.js.
213+
```
214+
The build file will be imported in a separate directory in the project's root.
215+
Enter the name of this directory or press Enter if you like to go with default.
216+
(component-dist)
217+
```
167218

168-
You have to copy the URL/link to the build file and enter it and the generator will download it for you in a directory named ```component-dist```. If this directory (component-dist) already exists then enter ```skip``` and enter the URL in the next question (given below).
219+
Once you have your build directory ready, generator will show you a URL, which containts the component's directory. You can find the build file in the root folder or a separate folder named build, dist, etc. The build file is generally named index.js, package_name.js, index.min.js or package_name.min.js, etc. Copy the URL of the build file and paste it in the generator.
169220

170-
```bash
221+
```
171222
This URL - https://www.jsdelivr.com/package/npm/<your-package-name>?version=<your-package-version>
172-
contains the directory of the package, please find the build file (generally in the dist or build
173-
folder) and paste the link here, we will download it for you in the existing folder.
223+
contains the directory of the package, please find the build file (generally in the dist or build
224+
folder) and paste the link here, we will download it for you.
174225
```
175226

176-
D) After successfully importing the build file, you will be asked the same questions (questions A and B in the next section) about your component as asked while [making a new one](#make-a-new-web-component).
227+
The generator will download the build file in the build directory. Next, the questions in [this](#make-a-new-web-component) section will be asked.
228+
229+
C) After successfully installing the component/importing the build file, you will be asked the same questions (questions A and B in the next section) about your component as asked while [making a new one](#make-a-new-web-component).
177230

178231
### Make a new Web Component
179232

180233
A) Enter computer package name. This should contain only small alphabets and hyphen ( - ) between the words. You can't use CAPITAL letters, number, space, any other special character(s) and hyphen at beginning or end.
181234

182-
```bash
235+
```
183236
Computer package name? This is a computer name with NO capital letters or special
184237
characters apart from the hyphen ( - ) .
185238
```
186239

187240
B) Enter human name for the project. This can only contain letters (small and capital) and spaces, no other special characters or numbers.
188241

189-
```bash
242+
```
190243
Thanks! Now, give me a human name for the project with only letters and NO special
191244
characters apart from the whitespace (space). e.g. \"Genome Browser\"
192245
```

0 commit comments

Comments
 (0)