Repository: incubator-distributedlog Updated Branches: refs/heads/master 2d6f98abb -> 5d5fa3188
Add instructions for building website and documentation Author: Sijie Guo <[email protected]> Author: Sijie Guo <[email protected]> Reviewers: Leigh Stewart <[email protected]> Closes #30 from sijie/sijie/add_instructions_for_building_website Project: http://git-wip-us.apache.org/repos/asf/incubator-distributedlog/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-distributedlog/commit/5d5fa318 Tree: http://git-wip-us.apache.org/repos/asf/incubator-distributedlog/tree/5d5fa318 Diff: http://git-wip-us.apache.org/repos/asf/incubator-distributedlog/diff/5d5fa318 Branch: refs/heads/master Commit: 5d5fa3188bf2f0fdbe99c03d8fd544839788a902 Parents: 2d6f98a Author: Sijie Guo <[email protected]> Authored: Sat Oct 22 08:57:00 2016 -0700 Committer: Sijie Guo <[email protected]> Committed: Sat Oct 22 08:57:00 2016 -0700 ---------------------------------------------------------------------- docs/README.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++ website/README.md | 56 +++++++++++--------------------- 2 files changed, 106 insertions(+), 37 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-distributedlog/blob/5d5fa318/docs/README.md ---------------------------------------------------------------------- diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..88d8855 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,87 @@ +This README gives an overview of how to build and contribute to the documentation of Apache DistributedLog. + +The documentation is included with the source of Apache DistributedLog in order to ensure that you always +have docs corresponding to your checked out version. The online documentation at +http://distributedlog.incubator.apache.org/docs/latest is also generated from the files found at master branch. + +# Requirements + +First, make sure you have Ruby installed. The minimal ruby version is 2.0.0. + +The dependencies are declared in the Gemfile in this directory. We use [reStructuredText](http://docutils.sourceforge.net/rst.html) +to write and [Jekyll](https://jekyllrb.com/) and [jekyll-rst](https://github.com/xdissent/jekyll-rst) to translate the documentation to static HTML. +You can use Ruby's Bundler Gem to install all the depenencies for building the documentation: + + gem install bundler + bundle install + +And use [pip](https://pypi.python.org/pypi/pip) to install docutils and pygments + + pip install docutils pygments + +# Build + +## Live developement + +While you are working with the documentation, you can test and develop live. Run the following in the root folder of the `docs`: + + $ bundle exec jekyll serve + +Jekyll will start a webserver on port `4000`. As you make changes to the content, Jekyll will rebuild it automatically. +This is helpful if you want to see how your changes will render in realtime. + +## Generating the static website + +Once you are done with your changes, you need to compile the static content for the website. +This is what is actually hosted on the Apache DistributedLog documentation site. + +You can build the static content by running the following command in the root docs directory: + + $ jekyll build + +Once built, it will be placed in the folder `_site` inside of the root directory. This directory will include images, HTML, CSS, and so on. + +# Contribute + +## reStructuredText + +The documentation pages are written in [reStructuredText](http://docutils.sourceforge.net/rst.html). It is possible to use [Markdown](http://daringfireball.net/projects/markdown/syntax) and intermix plain html. + +## Front matter + +In addition to Markdown, every page contains a Jekyll front matter, which specifies the title of the page and the layout to use. +The title is used as the top-level heading for the page. + +There are two layouts (found in `_layouts`) used for writing documentation: one is `default`, while the other one is `guide`. +The pages that use `default` layout will not have navigation side bar, while the pages that use `guide` layout will have +navigation side bar. The pages under `user-guide` and `admin-guide` are written using `guide` layout. + + --- + title: "Title of the Page" + layout: default + --- + +Furthermore, you can access variables found in `docs/_config.yml` as follows: + + {{ site.NAME }} + +This will be replaced with the value of the variable called `NAME` when generating the docs. + +## Structure + +### Documentation + +#### Navigation + +The navigation on the left side of the docs is automatically generated when building the docs. You can modify the markup in `_layouts/guide.html`. + +The structure of the navigation is determined by the front matter of all pages. The fields used to determine the structure are: + +- `nav-id` => ID of this page. Other pages can use this ID as their parent ID. +- `nav-parent_id` => ID of the parent. This page will be listed under the page with id `nav-parent_id`. + +Level 0 is made up of all pages, which have nav-parent_id set to `_root_`. There is no limitation on how many levels you can nest. + +The `title` of the page is used as the default link text. You can override this via `nav-title`. The relative position per navigational level is determined by `nav-pos`. + +The nesting is also used for the breadcrumbs like `User Guide > API > Best Practise`. http://git-wip-us.apache.org/repos/asf/incubator-distributedlog/blob/5d5fa318/website/README.md ---------------------------------------------------------------------- diff --git a/website/README.md b/website/README.md index f07ff10..2efe425 100644 --- a/website/README.md +++ b/website/README.md @@ -22,58 +22,40 @@ website. This is the static content is what is actually hosted on the Apache DistributedLog website. ### Development setup -Before working with the Jekyll code, you will need to install Jekyll: - $ gem install jekyll - $ gem install jekyll-redirect-from - $ gem install html-proofer +First, make sure you have Ruby installed. The minimal ruby version is 2.0.0. + +Before working with the Jekyll code, you can use Ruby's Bundler Gem to install all the dependencies for building this website: + + gem install bundler + bundle install *If you are on a Mac, you may need to install [Ruby Gems](https://rubygems.org/pages/download).* -### Live development -While you are working with the website, you can test and develop live. Run the -following command in the root folder of the website: - - $ jekyll serve +And use [pip](https://pypi.python.org/pypi/pip) to install docutils and pygments required for building the documentation: -Jekyll will start a webserver on port `4000`. As you make changes to the -content, Jekyll will rebuild it automatically. This is helpful if you want to see -how your changes will render in realtime. + pip install docutils pygments -In addition, you can run the tests via: +### Build website together with documentation - $ rake test +You can run the `build.sh` at the root folder of `website` to build a local site. -### Generating the static website -Once you are done with your changes, you need to compile the static -content for the website. This is what is actually hosted -on the Apache DistributedLog website. + $ build.sh local -You can build the static content by running the following command in the root -website directory: +You can also build with the production settings. It will generate the content that is actually hosted in distributedlog website. - $ jekyll build + $ build.sh production -Once built, it will be placed in the folder `content` inside of the root directory. -This directory will include images, HTML, CSS, and so on. In a typical Jekyll install -this content would live in `_site` - it has been changed for the Apache DistributedLog website +Once built, it will be placed in the folder `content` inside of the root directory. +This directory will include images, HTML, CSS and so on. In a typical Jekyll install +this content will live in `_site` - it has been changed for Apache DistributedLog website to work with the ASF Incubator publishing system. -### Apache License ---- -Except as otherwise noted this software is licensed under the -[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html) +### Run the server locally -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at +You can run `bundle exec jekyll serve` locally to serve the generated static content to verify if the website works as expected. - http://www.apache.org/licenses/LICENSE-2.0 + $ bundle exec jekyll serve -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License.
