testea/test-repo
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

clean up website readme, remove old deploy script (#8040)

Browse Source
This commit is contained in:
Georgii Dolzhykov authored and GitHub committed 2020-04-14 19:27:25 +03:00
1 parent c9335644d7
commit 670e069519
5 files changed
+39 -109
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CONTRIBUTING.md
+1 -1
View File
@@ -17,7 +17,7 @@ Here's what you need to know about the tests:
- `DEEP_COMPARE` That formats each file, then formats the output again, and checks that the second output is the same as the first.
- Each test folder has a `jsfmt.spec.js` that runs the tests. For JavaScript files, generally you can just put `run_spec(__dirname, ["babel", "flow", "typescript"]);` there. This will verify that the output using each parser is the same. You can also pass options as the third argument, like this: `run_spec(__dirname, ["babel"], { trailingComma: "es5" });`
- `tests/flow/` contains the Flow test suite, and is not supposed to be edited by hand. To update it, clone the Flow repo next to the Prettier repo and run: `node scripts/sync-flow-tests.js ../flow/tests/`.
- If you would like to debug prettier locally, you can either debug it in node or the browser. The easiest way to debug it in the browser is to run the interactive `docs` REPL locally. The easiest way to debug it in node, is to create a local test file with some example code you want formatted and either run it in an editor like VS Code or run it directly via `./bin/prettier.js <your_test_file>`.
- If you would like to debug prettier locally, you can either debug it in Node or the browser. The easiest way to debug it in Node, is to create a local test file with some example code you want formatted and either run it in an editor like VS Code or run it directly via `./bin/prettier.js <your_test_file>`. The easiest way to debug it in the browser is to build Prettier's website locally (see `website/README.md`).
Run `yarn lint:eslint --fix` to automatically format files.
scripts/build-docs.js
+1 -1
View File
@@ -25,7 +25,7 @@ if (isPullRequest) {
const newPkg = { ...pkg, version: `999.999.999-pr.${process.env.REVIEW_ID}` };
pipe(JSON.stringify(newPkg, null, 2)).to("package.json");
shell.exec("yarn build");
pipe(JSON.stringify(pkg, null, 2)).to("package.json"); // restore
pipe(JSON.stringify(pkg, null, 2) + "\n").to("package.json"); // restore
}
shell.cp(`${prettierPath}/standalone.js`, `${docs}/`);
shell.cp(`${prettierPath}/parser-*.js`, `${docs}/`);
website/README.md
+37 -83
View File
@@ -2,30 +2,50 @@
https://prettier.io/
## Setup
## Getting started
1. Build the Prettier browser libs for the playground by running the following in the project root dir:
1. Build the Prettier browser libs for the Playground by running the following in the project root directory:
```sh
cd your/path/to/prettier
yarn build-docs
```
(To build for master, use `PULL_REQUEST=true yarn build-docs`)
To build for the current branch, use `PULL_REQUEST=true yarn build-docs`. Otherwise, a release version of Prettier from `node_modules` is used.
2. Switch to the `website` directory and start the development server:
2. Switch to the `website` dir and start the server:
```sh
cd website
yarn start
```
## Configuration
This starts a server hosting the website locally at `http://localhost:3000/`. Any changes to the site's source files are reflected after refreshing the page, i.e. the server does not need to be restarted to show changes.
In the project repo, the `docs` folder is used to hold documentation written in markdown. A `blog` folder can be used to hold blog posts written in markdown.
## Docusaurus
### Document and Blog Front Matters
The site is built on [Docusaurus](https://docusaurus.io/), a static site generator for documentation sites.
Documentation should contain front matter that follows this example:
Its main configuration file is `siteConfig.js` ([docs](https://docusaurus.io/docs/en/site-config)).
Pages can be added to the site by putting `.js` files with React components in `pages/`. If you want to use code from other files in these pages, be aware of [how `require` works in Docusaurus](https://docusaurus.io/docs/en/api-pages#page-require-paths). It's also possible to include `.html` files directly. They are served as is and don't have any of the header, footer, or styles shared by the rest of Docusaurus. This is the way the Playground is hooked up (`pages/playground/index.html`).
Images and other static assets are placed inside the `static` directory: `static/img/your-image.png` is mapped to `http://prettier.io/img/your-image.png`. Any `.css` files in `static/` are concatenated to the standard styles provided by Docusaurus and used site-wide.
Please run <code>yarn svgo _path/to/image.svg_</code> before committing a new SVG to the repository.
## Playground
The Playground is not integrated with the Docusaurus infrastructure. Its UI (`website/playground/`) is built separately with webpack configured to put the resulting bundle in Docusaurus's `static` directory. The `yarn start` command (in `website/`) concurrently starts both Docusaurus's local server and webpack in the watch mode for the Playground.
Another part of the Playground is a web worker where formatting happens. It's not managed by webpack and resides directly in `static/worker.js`. It expects to find the [UMD bundles of Prettier](https://prettier.io/docs/en/browser.html) in `static/lib/`. That's why running `yarn build-docs` or `PULL_REQUEST=true yarn build-docs` in the project root is a required step.
Finally, there is a service worker that caches Prettier's relatively heavy bundles (`static/service-worker.js`).
## Documentation
In the project repo, the `docs` directory is used to hold documentation written in Markdown.
The front matter of documentation files should follow this example:
```yaml
id: doc1 # used for docs to find each other and to map links
@@ -40,88 +60,22 @@ next: doc2 # next doc on the sidebar for navigation
```
Blog posts should be written as markdown files with the following front matter:
The docs from `docs/` are published to `https://prettier.io/docs/en/next/` and are considered to be the docs of the next (not yet released) version of Prettier. When a release happens, the docs from `docs/` are copied to the `website/versioned_docs/version-stable` directory, whose content is published to `https://prettier.io/docs/en`.
## Blog
The `website/blog` directory contains blog posts written in Markdown. Their front matter should follow this example:
```yaml
title: Blog Post Title
author: Author Name
authorURL: http://twitter.com/author # (or some other link)
authorFBID: 21315325 # id to get author's picture
authorURL: http://github.com/author # (or some other link)
---
```
In the blog post you should include a line `<!--truncate-->`. This will determine under which point text will be ignored when generating the preview of your blog post. Blog posts should have the file name format: `yyyy-mm-dd-your-file-name.md`.
In the blog post, you should include a line `<!--truncate-->`. This determines under which point text will be ignored when generating the preview of your blog post. Blog posts should have the file name format: `yyyy-mm-dd-your-file-name.md`.
### Language Configurations
## Static Build
The `examples` script will generate a `languages.js` file and `i18n` folder for translation support, but if you only wish to support English, then these are not needed.
### Site Configurations
Configure the siteConfig.js file which has comments guiding you through what needs to be done and how each configuration affects your website.
Customize core/Footer.js which will serve as the footer for each page on your website.
Include your own top-level pages as React components in `pages/`. These components should just be the body sections of the pages you want, and they will be included with the header and footer that the rest of Docusaurus uses. Examples are provided for your reference. Currently, if you want to add other React components to your pages, you must include all of it inside that file due to how `require` paths are set-up. You may also include `.html` files directly, but this is not recommended, and these will just be served as is and will not have any of the header/footer/styles shared by the rest of Docusaurus.
All images and other static assets you wish to include should be placed inside the `static` folder. Any `.css` files provided in `static` will be concatenated to the standard styles provided by Docusaurus and used site-wide.
Files placed in `static/` will be accessible in the following way: `static/img/image.png` will be accessible at `img/image.png`.
Please run <code>yarn svgo _path/to/image.svg_</code> before committing a new SVG to the repository.
## Using Docusaurus
### Run the Server
To run your website locally run the script:
```bash
yarn start
```
This will start a server hosting your website locally at `localhost:3000`. This server will ignore any occurrences `siteConfig.baseUrl` in URLs, e.g. `localhost:3000/your-site/index.html` will be the same as `localhost:3000/index.html`. Any changes to configured files will be reflected by refreshing the page, i.e. the server does not need to be restarted to show changes.
### Build Static Pages
To create a static build of your website, run the script:
```bash
yarn build
```
This will generate `.html` files from all of your docs and other pages included in `pages/`. This allows you to check whether or not all your files are being generated correctly. The build folder is inside Docusaurus's directory inside `node_modules`.
### Publishing Your Website
Use CircleCI to publish your website whenever your project repo is updated. Configure your circle.yml file in your project repo to run commands to publish to GitHub Pages. An example is shown here:
```yaml
machine:
node:
version: 6.10.3
npm:
version: 3.10.10
test:
override:
- "true"
deployment:
website:
branch: master
commands:
- git config --global user.email "test-site-bot@users.noreply.github.com"
- git config --global user.name "Website Deployment Script"
- echo "machine github.com login test-site-bot password $GITHUB_TOKEN" > ~/.netrc
- cd website && npm install && GIT_USER=test-site-bot npm run publish-gh-pages
```
Note that in this case a GitHub user `test-site-bot` is created to use just for publishing. Make sure to give your Git user push permissions for your project and to set a GITHUB_TOKEN environment variable in Circle if you choose to publish this way.
If you wish to manually publish your website with the `publish-gh-pages` script, run the following example command with the appropriate variables for your project:
```
DEPLOY_USER=deltice GIT_USER=test-site-bot CIRCLE_PROJECT_USERNAME=deltice CIRCLE_PROJECT_REPONAME=test-site CIRCLE_BRANCH=master npm run publish-gh-pages
```
To create a static build of the website, run `yarn build` (in `website/`). The result will be put in `website/build/`.
website/deploy.sh
-23
View File
@@ -1,23 +0,0 @@
#!/bin/bash
if [ "$NODE_ENV" = production ]; then
echo "info: skipping deploy in production builds"
exit 0
fi
if [ ! "$GITHUB_TOKEN" ]; then
>&2 echo "error: GITHUB_TOKEN not present in env"
exit 1
fi
git config --global user.email "prettier-bot@users.noreply.github.com"
git config --global user.name "Prettier Bot"
echo "machine github.com login prettier-bot password $GITHUB_TOKEN" > ~/.netrc
cd website
export GIT_USER=prettier-bot
export CIRCLE_BRANCH=$TRAVIS_BRANCH
export CIRCLE_PROJECT_USERNAME=prettier
export CIRCLE_PROJECT_REPONAME=prettier
export CI_PULL_REQUEST=$TRAVIS_PULL_REQUEST_BRANCH
yarn --pure-lockfile && yarn run publish-gh-pages
website/package.json
-1
View File
@@ -2,7 +2,6 @@
"license": "MIT",
"scripts": {
"build": "webpack -p && docusaurus-build",
"publish-gh-pages": "docusaurus-publish",
"start": "concurrently \"docusaurus-start\" \"webpack -d -w\"",
"svgo": "svgo --pretty --indent=2 --config=svgo.yml",
"svgo-all": "find static | grep '\\.svg$' | xargs -Iz -n 1 yarn svgo z",