Skip to content

Commit

Permalink
Updating README with the information for non-docker users
Browse files Browse the repository at this point in the history
  • Loading branch information
imtodor authored Dec 13, 2018
1 parent d464d28 commit 9e6f0d7
Showing 1 changed file with 45 additions and 10 deletions.
55 changes: 45 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
Contains the documentation site implementation.

- [Local Setup :computer:](#local-setup)
- [Troubleshooting :hankey:](#troubleshooting)
- [Extra Features :moneybag:](#extra-features)

## Local Setup
This section describes the best practices about what and how should be done in order to run the documentation locally.
Expand All @@ -12,7 +14,9 @@ This section describes the best practices about what and how should be done in o
- Choose a repo you want to contribute to (e.g. [https://github.com/telerik/xaml-docs.git](https://github.com/telerik/xaml-docs.git), we will refer to that repo later as 'MY-REPO')
- Pull the repo onto your hard drive (e.g. `"D:\Work\xaml-docs"`)

### Instructions
> IMPORTANT: In case you are not able to install and use Docker, please go to [Instructions (without Docker)](#instructions-without-docker), otherwise continue to the next section.
### Instructions (with Docker)
- Clone the current (seed) repo
```bash
git clone [email protected]:telerik/docs-seed.git
Expand All @@ -39,9 +43,40 @@ sh start-docs.sh
> For WPF and Silverlight, see how to pass an [additional config file](#additional-config-file).
### Troubleshooting
### Instructions (without Docker)
- Install ruby 2.3.3 ([64bit](https://dl.bintray.com/oneclick/rubyinstaller/rubyinstaller-2.3.3-x64.exe) or [32bit](https://dl.bintray.com/oneclick/rubyinstaller/rubyinstaller-2.3.3-x64.exe))
- Install Ruby DevKit ([64bit](https://dl.bintray.com/oneclick/rubyinstaller/DevKit-mingw64-64-4.7.2-20130224-1432-sfx.exe) or [32bit](https://dl.bintray.com/oneclick/rubyinstaller/DevKit-mingw64-32-4.7.2-20130224-1151-sfx.exe))
- Ensure everything is correctly installed, especially if you have previous versions installed on the machine (e.g. check whether the 'config.yml' file in the DevKit root folder contains the correct path to the ruby folder and check whether the system environmnet variables are correctly set).

> For more info on the above you can read the following article - http://jekyll-windows.juthilo.com/1-ruby-and-devkit/.
- Clone the current (seed) repo
```bash
git clone [email protected]:telerik/docs-seed.git
```

- Go to the directory in which you've pulled it (e.g. `D:\Work\docs-seed`)
- Open a terminal of your choice (e.g., gitBash)
- Run the following command by passing the MY-REPO path (the **quotes** are mandatory):
```bash
sh copy_local.sh "D:\Work\xaml-docs"
```

- Go to the MY-REPO directory
- Open a terminal of your choice (e.g., gitBash)
- Execute the following bash command in the root folder
```bash
bundle exec jekyll serve
```

- This is it! You can find the documentation site on server address which is written in the terminal: *http://127.0.0.1:4000/*. If you can't open the previous URL, replace the '127.0.0.1' with 'localhost' - *http://localhost:4000*.
> For example, for WPF documentation this would be: http://127.0.0.1:4000/devtools/wpf/
> If you want to change the host or port just pass the --host or --port arguments to the command above as an addition (e.g. `bundle exec jekyll serve --host=0.0.0.0 --port=1234`).
## Troubleshooting

#### Does Not Serve
### Does Not Serve

You executed `sh start-docs.sh` but you did not see any Jekyll output. Instead, the command ended with

Expand All @@ -57,42 +92,42 @@ winpty sh start-docs.sh

An alternative is to re-install Git Bash and choose the default Windows terminal this time. You can read more detailes in the following post: [Docker for Windows: Interactive Sessions in MinTTY Git Bash](https://willi.am/blog/2016/08/08/docker-for-windows-interactive-sessions-in-mintty-git-bash/).

#### Ctrl+C Does not Work
### Ctrl+C Does not Work

When you want to stop serving the docs, you may have to **repeat** the `Ctrl+C` command or **press** `Enter` after it.

#### .gitignore is Always Modified
### .gitignore is Always Modified

The scripts that copy the seed repo to the content repo (MY-REPO), also update the `.gitignore` file so as to avoid creating unstanged changes with work files that must not be commited. If you keep getting the `.gitignore` checked out, see what the change is with the original and commit to your repo the version that matches what the tool generates.

#### Performance
### Performance

Docker is a resource-intensive tool. If you are not using it on a daily basis, consider preventing it from running on startup. Right click its tray icon > Settings > General, uncheck "Start Docker when you log in". This can save you time when booting up/logging in, but you will need to explicitly start Docker before working on documentation.

Also, it tends to require a lot of HDD space, which may be an issue if you are running it on an SSD drive with limited capacity. You can reduce its quota by opening the Settings dialog > Advanced and either changing the image location, and/or reducing its max size. This also lets you limit its RAM consumption.

### Extra Features
## Extra Features

You can benefit from the following features:
* [additional config file](#additional-config-file)
* [live sync](#livesync)
* [build without serve](#only-build)

#### Additional Config File
### Additional Config File

In case you want to add an additional config.yml file, pass it to the above command as follows:
```bash
sh start-docs.sh _silverlight.yml
```
#### LiveSync
### LiveSync
To be able to monitor the changes you are making on the built documentation, execute the following command in a new terminal in the root directory of the site:
```bash
sh watch.sh
```

> **Prerequisite**: If you haven't yet, please install [Node.js](https://nodejs.org/en/).
#### Only Build
### Only Build

To only run `jekyll build` and not `jekyll serve`, you need to execute the following bash command:
```bash
Expand Down

0 comments on commit 9e6f0d7

Please sign in to comment.