distributedlog-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From si...@apache.org
Subject incubator-distributedlog git commit: Add instructions for building website and documentation
Date Sat, 22 Oct 2016 15:57:04 GMT
Repository: incubator-distributedlog
Updated Branches:
  refs/heads/master 2d6f98abb -> 5d5fa3188


Add instructions for building website and documentation

Author: Sijie Guo <sijieg@twitter.com>
Author: Sijie Guo <sijie@apache.org>

Reviewers: Leigh Stewart <lstewart@twitter.com>

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 <sijieg@twitter.com>
Authored: Sat Oct 22 08:57:00 2016 -0700
Committer: Sijie Guo <sijie@apache.org>
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.
 


Mime
View raw message