| |
| |
| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <title>Documentation</title> |
| <meta name="description" content=""> |
| <meta name="author" content="The Apache Software Foundation"> |
| |
| <!-- Enable responsive viewport --> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" /> |
| |
| <!-- Le HTML5 shim, for IE6-8 support of HTML elements --> |
| <!--[if lt IE 9]> |
| <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script> |
| <![endif]--> |
| |
| <!-- Le styles --> |
| <link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"> |
| <link href="https://fonts.googleapis.com/icon?family=Material+Icons"> |
| <link href="/assets/themes/submarine/bootstrap/css/bootstrap.css" rel="stylesheet"> |
| <link href="/assets/themes/submarine/css/style.css?body=1" rel="stylesheet" type="text/css"> |
| <link href="/assets/themes/submarine/css/syntax.css" rel="stylesheet" type="text/css" media="screen" /> |
| <!-- Le fav and touch icons --> |
| <!-- Update these with your own images |
| <link rel="shortcut icon" href="images/favicon.ico"> |
| <link rel="apple-touch-icon" href="images/apple-touch-icon.png"> |
| <link rel="apple-touch-icon" sizes="72x72" href="images/apple-touch-icon-72x72.png"> |
| <link rel="apple-touch-icon" sizes="114x114" href="images/apple-touch-icon-114x114.png"> |
| --> |
| <link rel="apple-touch-icon" sizes="180x180" href="/assets/themes/submarine/img/favicon/apple-touch-icon.png"> |
| <link rel="icon" type="image/png" sizes="32x32" href="/assets/themes/submarine/img/favicon/favicon-32x32.png"> |
| <link rel="icon" type="image/png" sizes="16x16" href="/assets/themes/submarine/img/favicon/favicon-16x16.png"> |
| <link rel="icon" type="image/png" href="/assets/themes/submarine/img/favicon/favicon.ico"> |
| <link rel="manifest" href="/assets/themes/submarine/img/favicon/manifest.json"> |
| <link rel="mask-icon" href="/assets/themes/submarine/img/favicon/safari-pinned-tab.svg" color="#438bc9"> |
| <meta name="theme-color" content="#ffffff"> |
| |
| <!-- Js --> |
| <script src="https://code.jquery.com/jquery-1.10.2.min.js"></script> |
| <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.3.15/angular.min.js"></script> |
| <script src="https://angular-ui.github.io/bootstrap/ui-bootstrap-tpls-2.5.0.js"></script> |
| <script src="/assets/themes/submarine/bootstrap/js/bootstrap.min.js"></script> |
| <script src="/assets/themes/submarine/js/docs.js"></script> |
| <script src="/assets/themes/submarine/js/anchor.min.js"></script> |
| <script src="/assets/themes/submarine/js/moment.min.js"></script> |
| <script src="/assets/themes/submarine/js/helium.controller.js"></script> |
| <script src="/assets/themes/submarine/js/medium.controller.js"></script> |
| |
| <!-- atom & rss feed --> |
| <link href="/atom.xml" type="application/atom+xml" rel="alternate" title="Sitewide ATOM Feed"> |
| <link href="/rss.xml" type="application/rss+xml" rel="alternate" title="Sitewide RSS Feed"> |
| </head> |
| |
| <body> |
| |
| <div class="navbar navbar-inverse navbar-fixed-top" role="navigation"> |
| <div class="container"> |
| <div class="navbar-header"> |
| <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a class="navbar-brand" href="/"> |
| <img src="/assets/themes/submarine/img/submarine_white_logo.png" style="margin-top: -6px;" width="80" alt="I'm submarine"> |
| <span style="margin-left: 0px;"> Apache Submarine </span> |
| <!-- <span style="margin-left: 4px; font-size: 16px; font-family: Arial;">0.4.0</span> --> |
| </a> |
| </div> |
| |
| <nav class="navbar-collapse collapse" role="navigation"> |
| <ul class="nav navbar-nav navbar-right"> |
| <!-- Quick Start --> |
| <li class="docs"> |
| <a href="#" data-toggle="dropdown" class="dropdown-toggle">Quick Start<b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="https://github.com/apache/submarine/blob/master/docs/userdocs/yarn">Submarine on YARN</a></li> |
| <li><a href="https://github.com/apache/submarine/blob/master/docs/userdocs/k8s">Submarine on K8s</a></li> |
| </ul> |
| </li> |
| |
| <!-- Download --> |
| <li><a href="/download.html">Download</a></li> |
| |
| <!-- Docs --> |
| <li><a href="https://github.com/apache/submarine/tree/master/docs">Docs</a></li> |
| |
| <!-- GitHub --> |
| <li> |
| <a href="https://github.com/apache/submarine">GitHub</a> |
| </li> |
| |
| <!-- Community --> |
| <li class="docs"> |
| <a href="#" data-toggle="dropdown" class="dropdown-toggle">Community<b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="/community/contributors.html">Contributors</a></li> |
| <li><a href="/community/member.html">Member</a></li> |
| </ul> |
| </li> |
| |
| <!-- Apache --> |
| <li class="docs"> |
| <a href="#" data-toggle="dropdown" class="dropdown-toggle">Apache<b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="http://www.apache.org/foundation/how-it-works.html">Apache Software Foundation</a></li> |
| <li><a href="http://www.apache.org/licenses/">Apache License</a></li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> |
| <li><a href="/assets.html">Assets</a></li> |
| <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| </div> |
| </div> |
| |
| |
| |
| |
| <div class="content"> |
| |
| |
| <div class="row"> |
| |
| <div class="sideMenu col-sm-3"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li><a href="/contribution/contributions.html">Contributions</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="active"><a href="/contribution/documentation.html" class="active">Documentation</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li><a href="/contribution/webapplication.html">Web Application</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| <div class="col-sm-9"> |
| <!-- |
| 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 |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| 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. |
| --> |
| |
| <h1>Contributing to Documentation</h1> |
| |
| <h2>Dev Mode</h2> |
| |
| <p>Apache Submarine is using <a href="https://jekyllrb.com/">Jekyll</a> which is a static site generator and <a href="https://pages.github.com/">Github Pages</a> as a site publisher.</p> |
| |
| <p>For the more details, see <a href="https://help.github.com/articles/about-github-pages-and-jekyll/">help.github.com/articles/about-github-pages-and-jekyll/</a>.</p> |
| |
| <h3>Requirements</h3> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text"># ruby --version >= 2.0.0 |
| # Install Bundler using gem |
| gem install bundler |
| |
| cd $SUBMARINE_HOME/docs |
| # Install all dependencies declared in the Gemfile |
| bundle install |
| </code></pre></figure> |
| <p>For the further information about requirements, please see <a href="https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/#requirements">here</a>.</p> |
| |
| <p>On OS X 10.9, you may need to do</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">xcode-select --install |
| |
| </code></pre></figure> |
| <h3>Run the website locally</h3> |
| |
| <p>If you don't want to encounter uglily rendered pages, run the documentation site in your local first.</p> |
| |
| <p>In <code>$SUBMARINE_HOME/docs</code> folder, run</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">bundle exec jekyll serve --watch |
| </code></pre></figure> |
| <p>Using the above command, Jekyll will start a web server at <code>http://localhost:4000</code> and watch the <code>/docs</code> directory to update.</p> |
| |
| <h2>Folder Structure & Components</h2> |
| |
| <p><code>docs/</code> folder is organized like below:</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">docs/ |
| ├── _includes/themes/submarine |
| │ ├── _navigation.html |
| │ └── default.html |
| ├── _layouts |
| ├── _plugins |
| ├── assets/themes/submarine -> {ASSET_PATH} |
| │ ├── bootstrap |
| │ ├── css |
| │ ├── img |
| │ └── js |
| ├── development/ *.md |
| ├── displaysystem/ *.md |
| ├── install/ *.md |
| ├── interpreter/ *.md |
| ├── manual/ *.md |
| ├── quickstart/ *.md |
| ├── rest-api/ *.md |
| ├── security/ *.md |
| ├── storage/ *.md |
| ├── Gemfile |
| ├── Gemfile.lock |
| ├── _config.yml |
| ├── index.md |
| └── ... |
| </code></pre></figure> |
| <ul> |
| <li><code>_navigation.html</code>: the dropdown menu in navbar</li> |
| <li><code>default.html</code> & <code>_layouts/</code>: define default HTML layout</li> |
| <li><code>_plugins/</code>: custom plugin <code>*.rb</code> files can be placed in this folder. See <a href="https://jekyllrb.com/docs/plugins/">jekyll/plugins</a> for the further information.</li> |
| <li><code>{ASSET_PATH}/css/style.css</code>: extra css components can be defined</li> |
| <li><code>{ASSET_PATH}/img/docs-img/</code>: image files used for document pages can be placed in this folder</li> |
| <li><code>{ASSET_PATH}/js/</code>: extra <code>.js</code> files can be placed</li> |
| <li><code>Gemfile</code>: defines bundle dependencies. They will be installed by <code>bundle install</code>.</li> |
| <li><code>Gemfile.lock</code>: when you run <code>bundle install</code>, bundler will persist all gems name and their version to this file. For the more details, see <a href="http://bundler.io/v1.10/man/bundle-install.1.html#THE-GEMFILE-LOCK">Bundle "The Gemfile Lock"</a></li> |
| <li><code>documentation_group</code>: <code>development/</code>, <code>displaysystem/</code>, <code>install/</code>, <code>interpreter/</code>...</li> |
| <li><code>_config.yml</code>: defines configuration options for docs website. See <a href="https://jekyllrb.com/docs/configuration/">jekyll/configuration</a> for the other available config variables.</li> |
| <li><code>index.md</code>: the main page of <code>http://submarine.apache.org/docs/<SUBMARINE_VERSION>/</code></li> |
| </ul> |
| |
| <h3>Markdown</h3> |
| |
| <p>Submarine documentation pages are written with <a href="http://daringfireball.net/projects/markdown/">Markdown</a>. It is possible to use <a href="https://help.github.com/categories/writing-on-github/">GitHub flavored syntax</a> and intermix plain HTML.</p> |
| |
| <h3>Front matter</h3> |
| |
| <p>Every page contains <a href="https://jekyllrb.com/docs/frontmatter/">YAML front matter</a> block in their header. Don't forget to wrap the front matter list with triple-dashed lines(<code>---</code>) like below. |
| The document page should start this triple-dashed lines. Or you will face 404 error, since Jekyll can't find the page.</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text">--- |
| layout: page |
| title: "Apache Submarine Tutorial" |
| description: "This tutorial page contains a short walk-through tutorial that uses Apache Spark backend. Please note that this tutorial is valid for Spark 1.3 and higher." |
| group: quickstart |
| --- |
| </code></pre></figure> |
| <ul> |
| <li><code>layout</code>: the default layout is <code>page</code> which is defined in <code>_layout/page.html</code>.</li> |
| <li><code>title</code>: the title for the document. Please note that if it needs to include <code>Submarine</code>, it should be <code>Apache Submarine</code>, not <code>Submarine</code>.</li> |
| <li><code>description</code>: a short description for the document. One or two sentences would be enough. This description also will be shown as an extract sentence when people search pages.</li> |
| <li><code>group</code>: a category for the document page, more than on group can be applied by using this syntax:</li> |
| </ul> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text"> group: |
| - group1 |
| - group2 |
| </code></pre></figure> |
| <h3>Headings</h3> |
| |
| <p>All documents are structured with headings. From these headings, you can automatically generate a <strong>Table of Contents</strong>. There is a simple rule for Submarine docs headings.</p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text"># Level-1 heading <- used only for the main title |
| ## Level-2 heading <- start with this |
| ### Level-3 heading |
| #### Level-4 heading <- won't be converted in TOC from this level |
| </code></pre></figure> |
| <h3>Table of contents (TOC)</h3> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text"><div id="toc"></div> |
| </code></pre></figure> |
| <p>Add this line below <code># main title</code> in order to generate a <strong>Table of Contents</strong>.</p> |
| |
| <p>Headings until <code>### (Level-3 heading)</code> are included to TOC.</p> |
| |
| <p>Default setting options for TOC are definded in <a href="https://github.com/apache/submarine/blob/master/docs/assets/themes/submarine/js/toc.js#L4">here</a>.</p> |
| |
| <h3>Adding new pages</h3> |
| |
| <p>If you're going to create new pages, there are some spots you need to add the location of the page.</p> |
| |
| <ul> |
| <li><strong>Dropdown menu in navbar</strong>: add your docs location to <a href="https://github.com/apache/submarine/blob/master/docs/_includes/themes/submarine/_navigation.html">_navigation.html</a></li> |
| <li><strong>Main index</strong>: add your docs below <a href="http://submarine.apache.org/docs/latest/#what-is-the-next">What is the next?</a> section in <a href="https://github.com/apache/submarine/blob/master/docs/index.md">index.md</a> with a short description. No need to do this if the page is for <strong>Interpreters</strong>.</li> |
| </ul> |
| |
| <h2>For committers only</h2> |
| |
| <h3>Bumping up version in a new release</h3> |
| |
| <p><code>SUBMARINE_VERSION</code> and <code>BASE_PATH</code> property in <code>_config.yml</code></p> |
| |
| <h3>Deploy to ASF svnpubsub infra</h3> |
| |
| <ol> |
| <li><p>generate static website in <code>./_site</code></p> |
| <figure class="highlight"><pre><code class="language-text" data-lang="text"># go to /docs under Submarine source |
| JEKYLL_ENV=production bundle exec jekyll build |
| </code></pre></figure></li> |
| <li><p>checkout ASF repo |
| <code> |
| svn co https://svn.apache.org/repos/asf/submarine asf-submarine |
| </code></p></li> |
| <li><p>copy <code>submarine/docs/_site</code> to <code>asf-submarine/site/docs/[VERSION]</code></p></li> |
| <li><p><code>svn commit</code></p></li> |
| </ol> |
| |
| </div> |
| |
| </div> |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <footer> |
| <!-- <p>© 2020 The Apache Software Foundation</p>--> |
| </footer> |
| </body> |
| </html> |
| |
