From 9210f6793bd76be8da3fce6e97cd9792be3b5107 Mon Sep 17 00:00:00 2001 From: rhymes Date: Tue, 30 Apr 2019 00:54:29 +0200 Subject: [PATCH] Improvements on dev docs (#2616) * Correct installation documentation * Add stylized titles * Add some changes to the getting started documentation * Add changes for the backend guide * Add changes for the design guide * Add testing / Q&A guide improvements * Minor fixes to contributing docs * More improvements to the general doc * Improvements for frontend guide --- docs/.gitdocs.json | 2 +- docs/backend/admin.md | 25 ++++++- docs/backend/algolia.md | 18 +++-- docs/backend/auth-github.md | 13 ++-- docs/backend/auth-twitter.md | 24 ++++-- docs/backend/authentication.md | 8 +- docs/backend/authorization.md | 12 ++- docs/backend/previewing-emails.md | 5 +- docs/backend/pusher.md | 12 +-- docs/backend/readme.md | 2 +- docs/contributing.md | 18 +++-- docs/design/{brand.md => branding.md} | 10 +-- docs/design/readme.md | 8 +- docs/design/{theming-model.md => theming.md} | 24 ++++-- docs/frontend/js-initializers.md | 38 ---------- docs/frontend/liquid-tags.md | 10 +-- docs/frontend/plain-js.md | 38 ++++++++++ docs/frontend/preact.md | 10 ++- docs/frontend/readme.md | 2 +- docs/frontend/webpacker.md | 27 +++---- docs/getting-started/config-env.md | 30 +++++--- docs/getting-started/db.md | 14 ++-- docs/getting-started/forking.md | 8 +- docs/getting-started/pull-request.md | 8 +- docs/getting-started/readme.md | 2 +- docs/getting-started/syncing.md | 36 ++++----- docs/installation/docker.md | 4 +- docs/installation/gitpod.md | 4 +- docs/installation/linux.md | 45 ++++++----- docs/installation/mac.md | 47 ++++++------ .../{postgres.md => postgresql.md} | 34 +++++---- docs/installation/readme.md | 17 +++-- docs/installation/windows.md | 74 +++++++++---------- docs/readme.md | 6 +- docs/self-hosting.md | 8 +- docs/technical-overview.md | 38 +++++----- docs/tests/acceptance-tests.md | 31 +++++++- docs/tests/code-coverage.md | 53 +++++++++++++ docs/tests/codeclimate.md | 10 ++- docs/tests/integration-tests.md | 30 ++++++-- docs/tests/preact-tests.md | 27 +++++-- docs/tests/readme.md | 33 +++++---- docs/tests/simplecov.md | 10 --- docs/tests/skip-ci | 7 -- docs/tests/skip-ci.md | 7 ++ docs/tests/unit-functional-tests.md | 35 +++++++++ docs/tests/unit-tests.md | 16 ---- 47 files changed, 568 insertions(+), 372 deletions(-) rename docs/design/{brand.md => branding.md} (85%) rename docs/design/{theming-model.md => theming.md} (60%) delete mode 100644 docs/frontend/js-initializers.md create mode 100644 docs/frontend/plain-js.md rename docs/installation/{postgres.md => postgresql.md} (57%) create mode 100644 docs/tests/code-coverage.md delete mode 100644 docs/tests/simplecov.md delete mode 100644 docs/tests/skip-ci create mode 100644 docs/tests/skip-ci.md create mode 100644 docs/tests/unit-functional-tests.md delete mode 100644 docs/tests/unit-tests.md diff --git a/docs/.gitdocs.json b/docs/.gitdocs.json index ee4de8131..10212c94d 100644 --- a/docs/.gitdocs.json +++ b/docs/.gitdocs.json @@ -9,7 +9,7 @@ "target": "_blank" }, { - "title": "dev.to", + "title": "DEV", "href": "https://dev.to", "target": "_blank" } diff --git a/docs/backend/admin.md b/docs/backend/admin.md index d7cfda0b5..466d8393e 100644 --- a/docs/backend/admin.md +++ b/docs/backend/admin.md @@ -2,6 +2,27 @@ title: Admin Panel --- -# Acessing the Admin Panel +# Accessing the admin panel -There is an admin panel located at `/admin`. To access this admin panel, you must use `pudit` to give a user the `admin` role. +There is an admin panel located at . + +To access the panel, you must be logged with a user with the `admin` role activated. + +To activate such a role, you can follow these instructions: + +- open the Rails console + +```shell +rails console +``` + +1. load the user object of for _bob_ (or whatever the username is) + +```ruby +Loading development environment (Rails 5.2.3) +[1] pry(main)> user = User.find_by(username: "bob") +[2] pry(main)> user.add_role(:admin) +[3] pry(main)> user.save! +``` + +Now you'll be able to access the [administration panel](http://localhost:3000/admin). diff --git a/docs/backend/algolia.md b/docs/backend/algolia.md index cf07abfae..47c4d6373 100644 --- a/docs/backend/algolia.md +++ b/docs/backend/algolia.md @@ -2,43 +2,49 @@ title: Algolia --- -# Algolia for Search and Caching +# Algolia for Search -Algolia is a third party service which powers the search and is a caching layer for various endpoints. When working with the API is very likely would need to utilize Algolia. You will need to sign up for a free-tier account, retrieve the keys and provide those keys to the Rails application. +Algolia is a third party service which powers the search. When working with the API is very likely would need to utilize Algolia. You will need to sign up for a free-tier account, retrieve the keys and provide those keys to the Rails application. -## Algolia: Sign up +## Sign up 1. Go to the Algolia sign up [page](https://www.algolia.com/apps/AJVD3Q9KL3/dashboard). -2. Choose one of the three methods of signing up. (email, github or google) +2. Choose one of the three methods of signing up: email, github or google. 3. Fill in your information. + ![algolia-up-1](https://user-images.githubusercontent.com/22895284/51078744-ad602c00-16ba-11e9-9f59-7f9f2cc0443f.png) 4. Select the datacenter's region. + ![algolia-up-2](https://user-images.githubusercontent.com/22895284/51078745-ad602c00-16ba-11e9-81ee-6ec3310919d9.png) 5. Fill in or skip the project information. + ![algolia-up-3](https://user-images.githubusercontent.com/22895284/51078746-ad602c00-16ba-11e9-9927-d790ce03761e.png) 6. You are all set up now! You can go to your dashboard. + ![algolia-up-4](https://user-images.githubusercontent.com/22895284/51078747-ad602c00-16ba-11e9-8654-67c4d0f2e651.png) 7. You can skip the tutorial, we will guide you through the process. Accept the [Terms and Conditions](https://www.algolia.com/policies/terms). + ![algolia-up-5](https://user-images.githubusercontent.com/22895284/51078748-ad602c00-16ba-11e9-8ff6-6becac2152ac.png) 8. All good! You can get your API keys now. -## Algolia: Get API keys +## Get API keys 1. [Sign up](#algolia-sign-up) or [Sign in](https://www.algolia.com/users/sign_in) to your Algolia account. 2. From your **Dashboard**, click on **API Keys**. + ![algolia-1](https://user-images.githubusercontent.com/22895284/51078770-2eb7be80-16bb-11e9-9dcc-ed6d9c52d935.png) 3. Change your keys accordingly (name of Algolia key -> name of our `ENV` variable): - ``` + ```text Application ID -> ALGOLIASEARCH_APPLICATION_ID Search-Only API Key -> ALGOLIASEARCH_SEARCH_ONLY_KEY Admin API KEY -> ALGOLIASEARCH_API_KEY diff --git a/docs/backend/auth-github.md b/docs/backend/auth-github.md index ab0e8e74c..7fff34363 100644 --- a/docs/backend/auth-github.md +++ b/docs/backend/auth-github.md @@ -4,16 +4,17 @@ title: GitHub Authentication # GitHub App and Authentication -Dev.to allows you to authenticate using Github. To use this authentication method in local development, you will need to set up a GitHub App and retrieves keys. Then you'll need to provide theses keys to the Rails application. +DEV allows you to authenticate using GitHub. To use this authentication method in local development, you will need to set up a GitHub App and retrieve its keys. Then you'll need to provide these keys to the Rails application. 1. [Sign in](https://github.com/settings/applications/new) in your GitHub account. -2. Fill in the form with an application name, descriptions and URLs `http://localhost:3000/`. Replace the `3000` port if you run DEV on other port. +2. Fill in the form with an application name, description and the URL `http://localhost:3000/`. Replace the port `3000` if you run DEV on another port. + ![github-1](https://user-images.githubusercontent.com/22895284/51085500-877a6c00-173a-11e9-913a-0dccad234cf3.png) -3. You will be redirected in the app's **Developer settings**. Here you will find the keys. Change them accordingly (name of Github key -> name of our `ENV` variable): +3. You will be redirected in the app's **Developer settings**. Here you will find the keys. Change them accordingly (name of GitHub key -> name of our `ENV` variable): - ``` + ```text Client ID -> GITHUB_KEY Client Secret -> GITHUB_SECRET ``` @@ -21,12 +22,14 @@ Dev.to allows you to authenticate using Github. To use this authentication metho ![github-2](https://user-images.githubusercontent.com/22895284/51085862-49337b80-173f-11e9-8503-f8251d07f458.png) 4. You will need a personal token as well. From the same dashboard, navigate to **Personal access tokens** and generate a new token. + ![github-3](https://user-images.githubusercontent.com/22895284/51085863-49337b80-173f-11e9-81bf-1c1e38035a7a.png) + 5. Fill in the token description and generate the token. 6. Be sure that you copy the token right away, because it is the only time you will see it. Change it accordingly. - ``` + ```shell Personal access tokens -> GITHUB_TOKEN ``` diff --git a/docs/backend/auth-twitter.md b/docs/backend/auth-twitter.md index 8215a561a..2a566bcaf 100644 --- a/docs/backend/auth-twitter.md +++ b/docs/backend/auth-twitter.md @@ -1,35 +1,40 @@ --- -title: Twitter Authenication +title: Twitter Authentication --- # Twitter App and Authentication -Dev.to allows you to authenicate using Twitter. In order to use this authenication method in local development you will need to setup a Twitter App and retrieves keys. Then you'll need to provide theses keys to the Rails application. +DEV allows you to authenticate using Twitter. In order to use this authentication method in local development you will need to setup a Twitter App and retrieve its keys. Then you'll need to provide these keys to the Rails application. -## Twitter: Sign up +## Sign up 1. [Sign in](https://developer.twitter.com/apps) to your Twitter account. 2. In order to get the API keys, you will have to apply for a developer account. Click the **Apply** button. + ![twitter-up-1](https://user-images.githubusercontent.com/22895284/51078779-53139b00-16bb-11e9-911c-f232e229872a.png) 3. Setup your Twitter account. Be sure you have your phone number and email address filled in. + ![twitter-up-2](https://user-images.githubusercontent.com/22895284/51078780-53139b00-16bb-11e9-91d5-08c9365ff08f.png) 4. Fill in your account information and give a name to your **developer account**. + ![twitter-up-3](https://user-images.githubusercontent.com/22895284/51078781-53ac3180-16bb-11e9-8cf4-005efbb92d8a.png) -5. Write down the reasons that you want to use Twitter API. Mention DEV community and describe the issues and tests and things that you want to work on. Copy it, you might use it later ;) +5. Write down the reasons that you want to use Twitter API. Mention DEV's community and describe the issues and tests and things that you want to work on. Copy it, you might use it later ;) + ![twitter-up-4](https://user-images.githubusercontent.com/22895284/51078782-53ac3180-16bb-11e9-9937-c888ae40143c.png) 6. Read :) and accept the Terms and Conditions. + ![twitter-up-5](https://user-images.githubusercontent.com/22895284/51078783-53ac3180-16bb-11e9-9cf1-8e009ada6e57.png) 7. Verify your email address once more and you will be done. 8. You are done. -## Twitter: Get API keys +## Get API keys 1. [Sign up](#twitter-sign-up) or [sign in](https://developer.twitter.com/apps) to your Twitter developer account. @@ -37,27 +42,34 @@ Dev.to allows you to authenicate using Twitter. In order to use this authenicati ![twitter-1](https://user-images.githubusercontent.com/22895284/51078797-9a019080-16bb-11e9-8130-1cd13008461e.png) 3. Fill in the app name, description and URL `https://dev.to`. + ![twitter-2](https://user-images.githubusercontent.com/22895284/51078798-9a019080-16bb-11e9-900d-d2677d7c43c4.png) 4. Check the **Enable Sign in with Twitter** option and fill in the Callback URL `http://localhost:3000/users/auth/twitter/callback` (or whatever port you run DEV on). + ![twitter-3](https://user-images.githubusercontent.com/22895284/51078799-9a9a2700-16bb-11e9-8e88-0393260449c7.png) + 5. Fill in the DEV information, **Terms of Service** `http://dev.to/terms` and **Privacy policy** `http://dev.to/privacy`. + ![twitter-4](https://user-images.githubusercontent.com/22895284/51078800-9a9a2700-16bb-11e9-9b36-d325a2624f5a.png) 6. Write down (or paste) the things that you will work on. Press **Create**. + ![twitter-5](https://user-images.githubusercontent.com/22895284/51078801-9a9a2700-16bb-11e9-9bd9-76c9ca1ba526.png) 7. Review the [Twitter Developer Terms](https://developer.twitter.com/en/developer-terms/agreement-and-policy.html) and agree to do nothing sketchy. + ![twitter-6](https://user-images.githubusercontent.com/22895284/51078802-9a9a2700-16bb-11e9-8789-53720bcfc9d9.png) 8. The app is all set! 9. One more change... From the app dashboard go to **Permissions** and check **Request email addresses from users** option. + ![twitter-7](https://user-images.githubusercontent.com/22895284/51078803-9a9a2700-16bb-11e9-8f27-dbfe04b52031.png) 10. From the same dashboard access the **Keys and tokens** and change them accordingly (name of Twitter key -> name of our `ENV` variable): - ``` + ```text API key -> TWITTER_KEY API secret key -> TWITTER_SECRET Access Token -> TWITTER_ACCESS_TOKEN diff --git a/docs/backend/authentication.md b/docs/backend/authentication.md index 5b865b8cf..8ed31d67e 100644 --- a/docs/backend/authentication.md +++ b/docs/backend/authentication.md @@ -4,9 +4,9 @@ title: Authentication # Authentication -Authenication is handled by [Devise](https://github.com/plataformatec/devise) and [OmniAuth](https://github.com/omniauth/omniauth) +Authentication is handled by [Devise](https://github.com/plataformatec/devise) and [OmniAuth](https://github.com/omniauth/omniauth). -On DEV.to you can only authenicate through Github or Twitter. Please check out the respective guides on how to authenicate: +On DEV you can only authenticate through GitHub or Twitter. Please check out the respective guides on how to authenticate: -- [Twitter App and Authenication](/installation/auth-github) -- [Github App and Authenication](/installation/auth-twitter) +- [Github authentication](/backend/auth-github) +- [Twitter authentication](/backend/auth-twitter) diff --git a/docs/backend/authorization.md b/docs/backend/authorization.md index bc68178d4..6a181044b 100644 --- a/docs/backend/authorization.md +++ b/docs/backend/authorization.md @@ -4,12 +4,10 @@ title: Authorization # Authorization -Authorization is handled by the third party gem [pundit](https://github.com/varvet/pundit). +Authorization is handled by the third party gem [Pundit](https://github.com/varvet/pundit) through the `authorize` method which you can find in various controllers, look for statements like: -The policies can be found in `/app/policies` - -Authorization is handled by the `authorize` method which you will find in various controllers - -```rb - authorize @user +```ruby +authorize @user ``` + +All authorization policies can be found in `/app/policies`. diff --git a/docs/backend/previewing-emails.md b/docs/backend/previewing-emails.md index e1e71d215..7551a33a2 100644 --- a/docs/backend/previewing-emails.md +++ b/docs/backend/previewing-emails.md @@ -4,5 +4,6 @@ title: Previewing Emails # Previewing emails in development -You can modify the test in `/test/mailers/previews` -You can view the previews at (for example) `http://localhost:3000/rails/mailers/notify_mailer/new_reply_email` +You can view email previews at . + +Previews are setup in the directory `spec/mailers/previews`. diff --git a/docs/backend/pusher.md b/docs/backend/pusher.md index fa3159e3d..2298c690d 100644 --- a/docs/backend/pusher.md +++ b/docs/backend/pusher.md @@ -2,25 +2,27 @@ title: Pusher --- -# Pusher - Real-Time Notification +# Pusher for Realtime Notifications -Pusher is third party service being used to power the chat system. When both DEV.to members follow each other they have the ability to use chat and converse with each other. +Pusher is a third party service being used to power the [chat system](https://dev.to/connect). In order to use the chat functionality within you development enviroment -you will need to sign up for a free-tier Pusher account and retrieves -keys. Then you'll need to provide those keys to the Rails application. +you will need to sign up for a free-tier Pusher account and retrieve +its keys. Then you'll need to provide those keys to the Rails application. 1. [Sign up](https://dashboard.pusher.com/accounts/sign_up) or [sign in](https://dashboard.pusher.com/) to your Pusher account. 2. Once signed in, fill in the prompt to create a new Pusher Channels app. + ![pusher-1](https://user-images.githubusercontent.com/22895284/51086056-058e4100-1742-11e9-8dca-de3e47e2bc73.png) 3. In your new Pusher Channels app, click the "App Keys" tab. + ![pusher-2](https://user-images.githubusercontent.com/22895284/51086057-058e4100-1742-11e9-9fb7-397187aa8689.png) 4. Change your keys accordingly (name of Pusher key -> name of our application key): - ``` + ```text app_id -> PUSHER_APP_ID key -> PUSHER_KEY secret -> PUSHER_SECRET diff --git a/docs/backend/readme.md b/docs/backend/readme.md index 15d0eb7e8..3694ff6a7 100644 --- a/docs/backend/readme.md +++ b/docs/backend/readme.md @@ -5,7 +5,7 @@ items: - auth-twitter.md - auth-github.md - authorization.md - - aloglia.md + - algolia.md - pusher.md - admin.md - previewing-emails.md diff --git a/docs/contributing.md b/docs/contributing.md index 99148d446..9d127c5c6 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -18,20 +18,26 @@ For more information on how to use GitDocs read the [GitDocs guide](https://gitd Install the [GitDocs NodeJs library](https://www.npmjs.com/package/gitdocs) +```shell +npm install gitdocs -g +``` + Specifying `-g` will install the library globally which is what you want to do. -``` -npm install gitdocs -g +If you use yarn you can instead issue: + +```shell +yarn global add gitdocs ``` Once installed, to run gitdocs you need to navigate to the root directory of the DEV.to codebase and run -``` +```shell gitdocs serve ``` -This will start a server on port `8000` +This will start a server where you can browse the documentation: -When you add new markdown pages you'll have to stop and start the -websever before you see them. +When you add new markdown pages or rename existing ones, you'll have to restart +the server before you notice any changes. diff --git a/docs/design/brand.md b/docs/design/branding.md similarity index 85% rename from docs/design/brand.md rename to docs/design/branding.md index bd9f6272b..277926710 100644 --- a/docs/design/brand.md +++ b/docs/design/branding.md @@ -1,16 +1,16 @@ --- -title: Branding Guideline +title: Branding Guidelines --- -# Branding Guideline +# Branding Guidelines -## Themeing +## DEV Theme DEV's design inspiration is meant to be a throwback. In personality and design it is ATARI inspired. Magazines like PAPER are also an inspiration in terms of being a [bold contrast with some more indy](https://www.google.com/search?biw=1440&bih=780&tbm=isch&sa=1&ei=KSN8W5WVLoy55gLI77TgBA&q=paper+magazine+cover&oq=paper+magazine+cover). We also think in terms of how people use the DEV brand for their own purposes. Profiles are very much public-facing records of what people have put out into the world. `dev.to/{username}` is your dev identity. -Imagine a developer’s face with the DEV heading above them. If we existed in the 80’s we would be DEV MAGAZINE, with the exact same branding. +Imagine a developer's face with the DEV heading above them. If we existed in the 80's we would have been "DEV MAGAZINE", with the exact same branding. ## Branding Rules @@ -24,4 +24,4 @@ Imagine a developer’s face with the DEV heading above them. If we existed in t ## Acknowledgments - We use the [Joystick](http://www.pixelsagas.com/?download=joystick) font by Neale Davidson and [Pixel Sagas](http://www.pixelsagas.com/) for the DEV Logo. We have a commercial license. -- Thank you to [EmojiOne](https://www.emojione.com/) for providing free emoji icons +- Thank you to [EmojiOne](https://www.emojione.com/) for providing free emoji icons. diff --git a/docs/design/readme.md b/docs/design/readme.md index 5b673c728..be0271e92 100644 --- a/docs/design/readme.md +++ b/docs/design/readme.md @@ -1,8 +1,8 @@ --- -title: Designer Guide +title: Design Guide items: - - brand.md - - theming-model.md + - branding.md + - theming.md --- -# Designer Guide +# Design Guide diff --git a/docs/design/theming-model.md b/docs/design/theming.md similarity index 60% rename from docs/design/theming-model.md rename to docs/design/theming.md index ceec86f8d..238d530ee 100644 --- a/docs/design/theming-model.md +++ b/docs/design/theming.md @@ -1,12 +1,18 @@ --- -title: Theming Model +title: Theming Guidelines --- -# Theming Model +# Theming Guidelines -DEV.to supports different themes such as Normal, Dark, Pink. These themes are powered by [css custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) which are loaded at runtime by javascript via `layouts/_user_config.html.erb`. +DEV supports different themes such as Default, Night, Pink. -``` +You can switch the theme at in the "Style Customization" section. + +These themes are powered by [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties), loaded at runtime by Javascript via `layouts/_user_config.html.erb`. + +An example of how it works: + +```javascript