|
1 | 1 | # Magento Developer Documentation |
2 | 2 |
|
3 | | -Welcome! This site contains the latest Magento developer documentation for ongoing Magento 2.x releases. |
| 3 | +This project contains the source code of the latest 2.0 Magento developer documentation archived. |
| 4 | +The resulting website is available at <https://commerce-docs.github.io/devdocs-archive/2.0/>. |
4 | 5 |
|
5 | | -To contribute, please fork the `develop` branch. |
| 6 | +## Building this site |
6 | 7 |
|
7 | | -# Building this site |
| 8 | +For local builds, you need to install Ruby 2.4 or later. |
8 | 9 |
|
9 | | -You can build this site locally in the following ways: |
| 10 | +To check the Ruby version on your environment, run in your terminal: |
10 | 11 |
|
11 | | -- [Installing the project dependencies locally](#build-using-jekyll) (Mac, Linux) |
12 | | -- [Using a Docker container](#build-using-docker) (Mac, Linux) |
13 | | -- [Using a Vagrant virtual machine](#build-using-vagrant) (Mac, Linux, Windows) |
| 12 | +```shell |
| 13 | +ruby -v |
| 14 | +``` |
14 | 15 |
|
15 | | -## Build using Jekyll |
| 16 | +See the [Ruby site](https://www.ruby-lang.org/en/documentation/installation) for installation instructions. |
16 | 17 |
|
17 | | -For local builds, you need to install [Bundler](http://bundler.io/), and [Ruby](https://www.ruby-lang.org) version manager. |
| 18 | +### Install Bundler |
18 | 19 |
|
19 | | -### To prepare your MacOS environment: |
20 | | -1. Install Homebrew. See the [Homebrew site](https://brew.sh) for instructions. |
21 | | -1. Use Homebrew to install a Ruby version manager. |
| 20 | +Install the [Bundler](https://bundler.io/) gem, which helps with Ruby dependencies: |
22 | 21 |
|
23 | | - ``` |
24 | | - $ brew install rbenv ruby-build |
25 | | - ``` |
26 | | - |
27 | | -1. Add rbenv to bash so that it loads every time you open a terminal. |
28 | | - |
29 | | - ``` |
30 | | - $ echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile |
31 | | - ``` |
| 22 | +```sh |
| 23 | +gem install bundler |
| 24 | +``` |
32 | 25 |
|
33 | | -1. Source your `.bash_profile` file. |
| 26 | +Once you have completed preparing your environment, you can build locally and review the site in your browser. |
34 | 27 |
|
35 | | - ``` |
36 | | - $ source ~/.bash_profile |
37 | | - ``` |
| 28 | +### Install devdocs |
38 | 29 |
|
39 | | -1. Install a specific version of Ruby. |
| 30 | +Clone or download the repository. The first time you are at the `devdocs` directory, run: |
40 | 31 |
|
41 | | - ``` |
42 | | - $ rbenv install 2.4.x |
43 | | - $ rbenv global 2.4.x |
44 | | - $ ruby -v |
45 | | - ``` |
| 32 | +```sh |
| 33 | +bundle install |
| 34 | +``` |
46 | 35 |
|
47 | | -1. Install the Bundler gem, which helps with Ruby dependencies. |
48 | | - |
49 | | - ``` |
50 | | - $ gem install bundler |
51 | | - ``` |
| 36 | +Once you have completed preparing your environment, you can build locally and review the site in your browser. |
52 | 37 |
|
53 | | -1. Run `bundle install` the first time you are in the `devdocs` directory or when you need to pick up theme changes. |
| 38 | +### Build and preview locally |
54 | 39 |
|
55 | | -### To build locally: |
56 | | -Once you have completed preparing your environment, you can build locally and review the site in your browser. |
| 40 | +[rake](https://github.com/ruby/rake) is a native Ruby tool that helps to automate tasks. |
57 | 41 |
|
58 | | -1. Run the serve command. |
| 42 | +1. Run the rake task that installs all required dependencies and starts the [Jekyll](https://jekyllrb.com/) server: |
59 | 43 |
|
| 44 | + ```sh |
| 45 | + rake preview |
60 | 46 | ``` |
61 | | - $ bundle exec jekyll serve --incremental |
62 | | -
|
63 | | - Configuration file: /Users/username/Github/devdocs/_config.yml |
64 | | - Source: /Users/username/Github/devdocs |
65 | | - Destination: /Users/username/Github/devdocs/_site |
66 | | - Incremental build: enabled |
67 | | - Generating... |
68 | | - done in x.x seconds. |
69 | | - Auto-regeneration: enabled for '/Users/username/Github/devdocs' |
70 | | - Server address: http://127.0.0.1:4000// |
71 | | - Server running... press ctrl-c to stop. |
72 | | - ``` |
73 | | - |
74 | | -1. Use the **Server address** URL `http://127.0.0.1:4000/` in a browser to preview the content. |
75 | 47 |
|
76 | 48 | 1. Press `Ctrl+C` in the serve terminal to stop the server. |
77 | 49 |
|
78 | | -> ***TIP*** |
79 | | -> Leave the serve terminal open and running. Every time you save changes to a file, it automatically regenerates the site so you can test the output immediately. Changing the `_config.yml` file requires a fresh build. Using the `--incremental` option limits re-builds to posts and pages that have changed. |
80 | | -
|
81 | | -## Build using Docker |
82 | | - |
83 | | -[This Docker container](https://github.com/magento-devdocs/docker-for-devdocs) contains everything necessary to run Jekyll3 for working with Magento DevDocs. |
84 | | - |
85 | | -## Build using Vagrant |
| 50 | +If rake fails on your environment, generate the preview using jekyll. |
86 | 51 |
|
87 | | -You can deploy the devdocs site locally using [this Vagrant project](https://github.com/magento-devdocs/vagrant-for-magento-devdocs). |
| 52 | +## Build and deploy (for admins) |
88 | 53 |
|
89 | | -*** |
| 54 | +The website is deployed using the [GitHub Pages](https://pages.github.com/) service. |
| 55 | +The builds are pushed to the 2.0 directory at the gh-pages branch. |
90 | 56 |
|
91 | | -If you have questions, open an issue and ask us. We're looking forward to hearing from you! |
| 57 | +To build and deploy the website, run: |
92 | 58 |
|
93 | | -* <a href="https://twitter.com/MagentoDevDocs" class="twitter-follow-button" data-show-count="false">Follow @MagentoDevDocs</a> |
| 59 | +```sh |
| 60 | +rake build_and_deploy |
| 61 | +``` |
94 | 62 |
|
95 | | -* <a href="mailto:[email protected]">E-mail us</a> |
| 63 | +The command performs the following actions: |
96 | 64 |
|
97 | | -* <a href="https://devdocs.magento.com">Visit our documentation site</a>, built using [GitHub pages](https://pages.github.com/). |
| 65 | +1. Clears the _site directory. |
| 66 | +1. Builds the website with the base URL `devdocs-archive/2.0`. |
| 67 | +1. Remembers the number of commit that's been built to use later in a commit message for reference. |
| 68 | +1. Checkouts the gh-pages branch. |
| 69 | +1. Copies the content of the _site directory to the 2.0 directory. |
| 70 | + The \_site directory is ignored by git that makes the build from the archived-docs-v2.0 available in the gh-pages branch. |
| 71 | +1. Adds and commits the changes with the message that has reference to the commit of the built source code (see item 3 in this list). |
| 72 | +1. Pushes the commit to the remote repository. |
| 73 | +1. Checkouts back to the source code branch. |
0 commit comments