You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by au...@apache.org on 2017/10/17 18:18:47 UTC
docs commit: CB-13349: Move "development" docs to /doc
Repository: cordova-docs
Updated Branches:
refs/heads/master 66921ad12 -> 246af51cf
CB-13349: Move "development" docs to /doc
- Move "development" docs (install, Develop, Build, Deploy) to /doc
- Add a bit of crosslinking
This closes #745
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/246af51c
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/246af51c
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/246af51c
Branch: refs/heads/master
Commit: 246af51cffb8636b5764c7f005bb8ec683217847
Parents: 66921ad
Author: Jan Piotrowski <pi...@gmail.com>
Authored: Wed Oct 4 18:08:48 2017 +0200
Committer: Audrey So <au...@apache.org>
Committed: Tue Oct 17 11:17:34 2017 -0700
----------------------------------------------------------------------
README.md | 262 +----------------------
doc/building-the-website.md | 11 +
doc/deploying-the-website.md | 36 ++++
doc/developing-the-website.md | 17 ++
doc/installing-a-development-environment.md | 150 +++++++++++++
doc/troubleshooting.md | 34 +++
6 files changed, 254 insertions(+), 256 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/246af51c/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index a9b5fff..9b50c28 100644
--- a/README.md
+++ b/README.md
@@ -9,28 +9,6 @@ This repository contains the source code for the Cordova website. This covers [c
* [Introduction](#introduction)
* [Table of Contents](#table-of-contents)
* [Installing](#installing)
- + [Ruby](#ruby)
- - [Mac OS X](#mac-os-x)
- - [Windows](#windows)
- - [Linux](#linux)
- - [Verify Ruby](#verify-ruby)
- + [Python](#python)
- - [Mac OS X](#mac-os-x-1)
- - [Windows](#windows-1)
- - [Linux](#linux-1)
- - [Verify Python](#verify-python)
- + [Node.js](#nodejs)
- - [Mac OS X & Windows](#mac-os-x--windows)
- - [Linux](#linux-2)
- - [Verify Node.js](#verify-nodejs)
- + [Dependencies](#dependencies)
- - [Ruby](#ruby-1)
- - [JavaScript](#javascript)
- + [Make (optional)](#make-optional)
- - [Windows](#windows-2)
- - [Mac OS X](#mac-os-x-2)
- - [Linux](#linux-3)
- - [Verify make](#verify-make)
* [Building](#building)
* [Developing](#developing)
+ [Docs Redirects](#docs-redirects)
@@ -39,166 +17,19 @@ This repository contains the source code for the Cordova website. This covers [c
* [Adding a Tool or a Showcase App](#adding-a-tool-or-a-showcase-app)
* [Writing a Blog Post](#writing-a-blog-post)
* [Troubleshooting](#troubleshooting)
- + [Error: EMF, too many open files](#error-emf-too-many-open-files)
- + [Error: spawn ENOENT](#error-spawn-enoent)
- + [Permission issues during Ruby install](#permission-issues-during-ruby-install)
- + [Other Problems](#other-problems)
* [Attributions](#attributions)
## Installing
-### Ruby
-
-Ruby 2.0 is required to build the docs. NOTE: *The docs will not build with Ruby 1.8, 1.9 or 2.4.*
-
-#### Mac OS X
-
-Install Homebrew from [this site][homebrew], and then run:
-
- brew install ruby@2.0
-
-#### Windows
-
-Follow these steps:
-
-1. Download [this installer][ruby_installer] from [this page][ruby_downloads].
-2. Run the downloaded file.
- 1. Use the default installation path (usually `C:\Ruby22`).
- 1. Make sure the **'add executable to path'** option is checked.
-3. Download [this Ruby DevKit self-extracting archive][ruby_devkit] from the [same website][ruby_downloads].
-4. Run the downloaded file.
- 1. Use the following extraction path: `C:\Ruby22DevKit`.
-5. Open `cmd.exe`.
- 1. Go to the extraction path:
-
- cd C:\Ruby22DevKit
- 1. Run these commands (following any instructions they give):
-
- ruby dk.rb init
- ruby dk.rb install
- 1. Close `cmd.exe`.
-
-#### Linux
-
-Run the commands from [this site][ruby_linux] that apply to your Linux distribution.
-
-#### Verify Ruby
-
-Verify your Ruby installation by running:
-
- ruby --version
-
-### Python
-
-Python 2.7 is also required to build the docs. NOTE: *The docs will not build with Python 3.0 or greater.*
-
-#### Mac OS X
-
-Mac OS X comes with Python 2.7 pre-installed. Else, follow these steps:
-
-1. Download [this installer][python_installer_mac] from [this page][python_downloads].
-2. Run the downloaded file.
-
-#### Windows
-
-Follow these steps:
-
-1. Download [this installer][python_installer_windows] from [this page][python_downloads].
-2. Run the downloaded file.
- 1. Use the default installation path
- 1. Make sure the **'add executable to path'** option is checked.
-
-#### Linux
-
-The latest version of CentOS, Fedora, Redhat Enterprise (RHEL) and Ubuntu come with Python 2.7 pre-installed. Else, follow the steps from [this site][python_linux].
-
-#### Verify Python
-
-Verify your Python installation by running:
-
- python --version
-
-The version must be 2.7.x.
-
-### Node.js
-
-#### Mac OS X & Windows
-
-Go to [this site][nodejs], and click the "Install" button. Then run the downloaded file and follow the on-screen instructions. Make sure that the option to **install NPM** is enabled, if you see one.
-
-#### Linux
-
-Linux, follow the instructions on [this site][linux_node].
-
-#### Verify Node.js
-
-Verify your Node.js installation by running:
-
- node --version
- npm --version
-
-### Dependencies
-
-#### Ruby
-
-Once Ruby and Node.js are installed, install Ruby dependencies by running:
-
- gem install bundler
- bundle install --path ./ruby_modules
-
-This will install the required Ruby Gems locally into a subfolder called `ruby_modules` in your repo folder. On some systems, the above commands need to be prefixed with `sudo`. Similarly on Windows, the `cmd` window in which those commands are to be run might need to have been "Run as Administrator."
-
-#### JavaScript
-
-Finally, install Node.js and JavaScript dependencies by running:
-
- npm install
-
-### Make (optional)
-
-The website can be built with Gulp or Make. The Gulp workflow is enabled by just installing all the JavaScript dependencies. The Make workflow usually allows for faster builds, but requires installation of the `make` tool.
-
-#### Windows
-
-Make can be installed on Windows from [this page][make_page] by downloading the [setup tool][make_setup] and running it.
-
-#### Mac OS X
-
-Make comes with the Xcode Command Line Tools. To install them, run:
-
- xcode-select --install
-
-#### Linux
-
-Make is installed by default on Linux.
-
-#### Verify make
-
-Verify your make installation by running:
-
- make --version
+See [doc/installing-a-development-environment.md](doc/installing-a-development-environment.md).
## Building
-To build the whole website, run:
-
- node_modules/.bin/gulp build --prod
-
-The built website will be in a folder called `build-prod`.
+See [doc/building-the-website.md](doc/building-the-website.md).
## Developing
-To work on the website and see changes live as you save, run:
-
- node_modules/.bin/gulp serve
-
-That command will build the site and start a local server. To work on only the website without the docs, add the `--nodocs` flag, as follows:
-
- node_modules/.bin/gulp serve --nodocs
-
-Alternatively, to dynamically rebuild the site and refresh the browser _when changes happen_ (again, optionally with the `--nodocs` flag), run:
-
- node_modules/.bin/gulp watch
+See [doc/developing-the-website.md](doc/developing-the-website.md).
### Docs Redirects
@@ -206,37 +37,7 @@ See [doc/redirects.md](doc/redirects.md).
## Deploying
-This section requires basic knowledge of SVN. If you do not know how to use SVN, refer to [this tutorial][svn].
-
-To build the full website, run:
-
- node_modules/.bin/gulp build --prod
-
-A folder called `build-prod` will be created, and will contain the built website. Then, in a directory *one level above* the `cordova-docs` repository, check out the SVN repository that contains the currently deployed website by running the following command (committer access required):
-
- cd ..
- svn checkout https://svn.apache.org/repos/asf/cordova/site cordova-website
-
-Then, move into the `cordova-website` repository and synchronise it with the SVN server:
-
- cd cordova-website
- svn update
-
-Copy the `cordova-docs/build-prod/` directory to the `public` directory in SVN like so:
-
- cd ..
- cp -R cordova-docs/build-prod/. cordova-website/public/
-
-Some files will be new (`?` in SVN, and need to be `svn add`ed) and some files will be changed (`M` in SVN; no action required). To see just the `?` changes, run:
-
- cd cordova-website
- svn status | grep "?"
-
-Once you are satisfied that you have added the required changes, commit with a message:
-
- svn commit -m "Updated docs"
-
-**NOTE**: The commit might take a while (up to 1 hour), depending on the number of files changed.
+See [doc/deploying-the-website.md](doc/deploying-the-website.md).
## Working on the Documentation
@@ -254,59 +55,8 @@ See [doc/blogpost.md](doc/blogpost.md).
## Troubleshooting
-### Error: EMF, too many open files
-
-Increase the maximum number of open files on the system:
-
- ulimit -n 10480
-
-### Error: spawn ENOENT
-
-Run:
-
- gulp clean
-
-### Permission issues during Ruby install
-
-You could try a different method to install Ruby. Checkout [rbenv][rbenvgh]. Instructions:
-
-1. Install rbenv
-
- brew install rbenv ruby-build
-
-2. Add `eval "$(rbenv init -)"` to the end of your `.bash_profile`:
-
- echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
-
-3. Install a version of `ruby` and set it to your local version:
-
- rbenv install 2.0.0-p647
- rbenv local 2.0.0-p647
-
-### Other Problems
-
-Please ask for help on the Slack channel. Join at [slack.cordova.io](http://slack.cordova.io/).
+See [doc/troubleshooting.md](doc/troubleshooting.md).
## Attributions
-For attributions for used open-source work, please see the attributions page: `www/attributions.html`.
-
-
-[ruby_linux]: https://www.ruby-lang.org/en/documentation/installation/#package-management-systems
-[homebrew]: http://brew.sh/
-[linux_node]: https://nodesource.com/blog/nodejs-v012-iojs-and-the-nodesource-linux-repositories#installing-node-js-v0-12
-[ruby_downloads]: http://rubyinstaller.org/downloads/
-[ruby_installer]: http://dl.bintray.com/oneclick/rubyinstaller/rubyinstaller-2.2.3.exe
-[ruby_devkit]: http://dl.bintray.com/oneclick/rubyinstaller/DevKit-mingw64-32-4.7.2-20130224-1151-sfx.exe
-[nodejs]: https://nodejs.org/
-[install_pip]: https://pip.pypa.io/en/latest/installing.html
-[svn]: http://svnbook.red-bean.com/en/1.7/svn.intro.quickstart.html
-[pr]: https://help.github.com/articles/using-pull-requests/
-[rbenvgh]: https://github.com/sstephenson/rbenv
-[python_downloads]: https://www.python.org/downloads/release/python-2711/
-[python_installer_mac]: https://www.python.org/ftp/python/2.7.11/python-2.7.11-macosx10.6.pkg
-[python_installer_windows]: https://www.python.org/ftp/python/2.7.11/python-2.7.11.amd64.msi
-[python_linux]: http://docs.python-guide.org/en/latest/starting/install/linux/
-[redirects]: www/_docs/redirects.yml
-[make_page]: http://gnuwin32.sourceforge.net/packages/make.htm
-[make_setup]: http://gnuwin32.sourceforge.net/downlinks/make.php
+For attributions for used open-source work, please see the attributions page: `www/attributions.html`.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/246af51c/doc/building-the-website.md
----------------------------------------------------------------------
diff --git a/doc/building-the-website.md b/doc/building-the-website.md
new file mode 100644
index 0000000..4e51ee1
--- /dev/null
+++ b/doc/building-the-website.md
@@ -0,0 +1,11 @@
+## Building
+
+To build the whole website, run:
+
+ node_modules/.bin/gulp build --prod
+
+The built website will be in a folder called `build-prod`.
+
+### Next steps
+
+If the build was successful and looks good you can [deploy](deploying-the-website.md).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/246af51c/doc/deploying-the-website.md
----------------------------------------------------------------------
diff --git a/doc/deploying-the-website.md b/doc/deploying-the-website.md
new file mode 100644
index 0000000..21b1fdc
--- /dev/null
+++ b/doc/deploying-the-website.md
@@ -0,0 +1,36 @@
+## Deploying
+
+This section requires basic knowledge of SVN. If you do not know how to use SVN, refer to [this tutorial][svn].
+
+To build the full website, run:
+
+ node_modules/.bin/gulp build --prod
+
+A folder called `build-prod` will be created, and will contain the built website. Then, in a directory *one level above* the `cordova-docs` repository, check out the SVN repository that contains the currently deployed website by running the following command (committer access required):
+
+ cd ..
+ svn checkout https://svn.apache.org/repos/asf/cordova/site cordova-website
+
+Then, move into the `cordova-website` repository and synchronise it with the SVN server:
+
+ cd cordova-website
+ svn update
+
+Copy the `cordova-docs/build-prod/` directory to the `public` directory in SVN like so:
+
+ cd ..
+ cp -R cordova-docs/build-prod/. cordova-website/public/
+
+Some files will be new (`?` in SVN, and need to be `svn add`ed) and some files will be changed (`M` in SVN; no action required). To see just the `?` changes, run:
+
+ cd cordova-website
+ svn status | grep "?"
+
+Once you are satisfied that you have added the required changes, commit with a message:
+
+ svn commit -m "Updated docs"
+
+**NOTE**: The commit might take a while (up to 1 hour), depending on the number of files changed.
+
+
+[svn]: http://svnbook.red-bean.com/en/1.7/svn.intro.quickstart.html
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/246af51c/doc/developing-the-website.md
----------------------------------------------------------------------
diff --git a/doc/developing-the-website.md b/doc/developing-the-website.md
new file mode 100644
index 0000000..46f0e4e
--- /dev/null
+++ b/doc/developing-the-website.md
@@ -0,0 +1,17 @@
+## Developing
+
+To work on the website and see changes live as you save, run:
+
+ node_modules/.bin/gulp serve
+
+That command will build the site and start a local server. To work on only the website without the docs, add the `--nodocs` flag, as follows:
+
+ node_modules/.bin/gulp serve --nodocs
+
+Alternatively, to dynamically rebuild the site and refresh the browser _when changes happen_ (again, optionally with the `--nodocs` flag), run:
+
+ node_modules/.bin/gulp watch
+
+### Next steps
+
+When you are done with developing you can [build](building-the-website.md) and [deploy](deploying-the-website.md).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/246af51c/doc/installing-a-development-environment.md
----------------------------------------------------------------------
diff --git a/doc/installing-a-development-environment.md b/doc/installing-a-development-environment.md
new file mode 100644
index 0000000..570e781
--- /dev/null
+++ b/doc/installing-a-development-environment.md
@@ -0,0 +1,150 @@
+## Installing
+
+### Ruby
+
+Ruby 2.0 is required to build the docs. NOTE: *The docs will not build with Ruby 1.8, 1.9 or 2.4.*
+
+#### Mac OS X
+
+Install Homebrew from [this site][homebrew], and then run:
+
+ brew install ruby@2.0
+
+#### Windows
+
+Follow these steps:
+
+1. Download [this installer][ruby_installer] from [this page][ruby_downloads].
+2. Run the downloaded file.
+ 1. Use the default installation path (usually `C:\Ruby22`).
+ 1. Make sure the **'add executable to path'** option is checked.
+3. Download [this Ruby DevKit self-extracting archive][ruby_devkit] from the [same website][ruby_downloads].
+4. Run the downloaded file.
+ 1. Use the following extraction path: `C:\Ruby22DevKit`.
+5. Open `cmd.exe`.
+ 1. Go to the extraction path:
+
+ cd C:\Ruby22DevKit
+ 1. Run these commands (following any instructions they give):
+
+ ruby dk.rb init
+ ruby dk.rb install
+ 1. Close `cmd.exe`.
+
+#### Linux
+
+Run the commands from [this site][ruby_linux] that apply to your Linux distribution.
+
+#### Verify Ruby
+
+Verify your Ruby installation by running:
+
+ ruby --version
+
+### Python
+
+Python 2.7 is also required to build the docs. NOTE: *The docs will not build with Python 3.0 or greater.*
+
+#### Mac OS X
+
+Mac OS X comes with Python 2.7 pre-installed. Else, follow these steps:
+
+1. Download [this installer][python_installer_mac] from [this page][python_downloads].
+2. Run the downloaded file.
+
+#### Windows
+
+Follow these steps:
+
+1. Download [this installer][python_installer_windows] from [this page][python_downloads].
+2. Run the downloaded file.
+ 1. Use the default installation path
+ 1. Make sure the **'add executable to path'** option is checked.
+
+#### Linux
+
+The latest version of CentOS, Fedora, Redhat Enterprise (RHEL) and Ubuntu come with Python 2.7 pre-installed. Else, follow the steps from [this site][python_linux].
+
+#### Verify Python
+
+Verify your Python installation by running:
+
+ python --version
+
+The version must be 2.7.x.
+
+### Node.js
+
+#### Mac OS X & Windows
+
+Go to [this site][nodejs], and click the "Install" button. Then run the downloaded file and follow the on-screen instructions. Make sure that the option to **install NPM** is enabled, if you see one.
+
+#### Linux
+
+Linux, follow the instructions on [this site][linux_node].
+
+#### Verify Node.js
+
+Verify your Node.js installation by running:
+
+ node --version
+ npm --version
+
+### Dependencies
+
+#### Ruby
+
+Once Ruby and Node.js are installed, install Ruby dependencies by running:
+
+ gem install bundler
+ bundle install --path ./ruby_modules
+
+This will install the required Ruby Gems locally into a subfolder called `ruby_modules` in your repo folder. On some systems, the above commands need to be prefixed with `sudo`. Similarly on Windows, the `cmd` window in which those commands are to be run might need to have been "Run as Administrator."
+
+#### JavaScript
+
+Finally, install Node.js and JavaScript dependencies by running:
+
+ npm install
+
+### Make (optional)
+
+The website can be built with Gulp or Make. The Gulp workflow is enabled by just installing all the JavaScript dependencies. The Make workflow usually allows for faster builds, but requires installation of the `make` tool.
+
+#### Windows
+
+Make can be installed on Windows from [this page][make_page] by downloading the [setup tool][make_setup] and running it.
+
+#### Mac OS X
+
+Make comes with the Xcode Command Line Tools. To install them, run:
+
+ xcode-select --install
+
+#### Linux
+
+Make is installed by default on Linux.
+
+#### Verify make
+
+Verify your make installation by running:
+
+ make --version
+
+### Next steps
+
+Now you have everything installed you can [develop](developing-the-website.md), [build](building-the-website.md) and [deploy](deploying-the-website.md).
+
+[ruby_linux]: https://www.ruby-lang.org/en/documentation/installation/#package-management-systems
+[homebrew]: http://brew.sh/
+[linux_node]: https://nodesource.com/blog/nodejs-v012-iojs-and-the-nodesource-linux-repositories#installing-node-js-v0-12
+[ruby_downloads]: http://rubyinstaller.org/downloads/
+[ruby_installer]: http://dl.bintray.com/oneclick/rubyinstaller/rubyinstaller-2.2.3.exe
+[ruby_devkit]: http://dl.bintray.com/oneclick/rubyinstaller/DevKit-mingw64-32-4.7.2-20130224-1151-sfx.exe
+[nodejs]: https://nodejs.org/
+[python_downloads]: https://www.python.org/downloads/release/python-2711/
+[python_installer_mac]: https://www.python.org/ftp/python/2.7.11/python-2.7.11-macosx10.6.pkg
+[python_installer_windows]: https://www.python.org/ftp/python/2.7.11/python-2.7.11.amd64.msi
+[python_linux]: http://docs.python-guide.org/en/latest/starting/install/linux/
+[make_page]: http://gnuwin32.sourceforge.net/packages/make.htm
+[make_setup]: http://gnuwin32.sourceforge.net/downlinks/make.php
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/246af51c/doc/troubleshooting.md
----------------------------------------------------------------------
diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md
new file mode 100644
index 0000000..478f19a
--- /dev/null
+++ b/doc/troubleshooting.md
@@ -0,0 +1,34 @@
+## Troubleshooting
+
+### Error: EMF, too many open files
+
+Increase the maximum number of open files on the system:
+
+ ulimit -n 10480
+
+### Error: spawn ENOENT
+
+Run:
+
+ gulp clean
+
+### Permission issues during Ruby install
+
+You could try a different method to install Ruby. Checkout [rbenv](https://github.com/sstephenson/rbenv). Instructions:
+
+1. Install rbenv
+
+ brew install rbenv ruby-build
+
+2. Add `eval "$(rbenv init -)"` to the end of your `.bash_profile`:
+
+ echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
+
+3. Install a version of `ruby` and set it to your local version:
+
+ rbenv install 2.0.0-p647
+ rbenv local 2.0.0-p647
+
+### Other Problems
+
+Please ask for help on the Slack channel. Join at [slack.cordova.io](http://slack.cordova.io)
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org