This is an automated email from the ASF dual-hosted git repository.
vieiro pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-netbeans-website.git
The following commit(s) were added to refs/heads/master by this push:
new fdc2fbe [NETBEANS-1867] Tutorial reviews and contributions (#276)
fdc2fbe is described below
commit fdc2fbea58536bab1ac5d6e0d0e441d3c1c5efe6
Author: Antonio Vieiro <vie...@users.noreply.github.com>
AuthorDate: Sat Jan 26 10:11:53 2019 +0100
[NETBEANS-1867] Tutorial reviews and contributions (#276)
- Using ":reviewed: 2019-01-26" to mark a tutorial as reviewed.
- Modified the "tutorials.gsp" template to include a note indicating if a
tutorial has not been reviewed yet.
- Added /kb/docs/contributing.asciidoc with instructions on how to
contribute tutorials.
---
.../src/content/kb/docs/contributing.asciidoc | 272 +++++++++++++++++++++
.../content/kb/docs/images/contributing-button.png | Bin 0 -> 48831 bytes
.../content/kb/docs/images/contributing-link.png | Bin 0 -> 5717 bytes
.../src/content/kb/docs/index.asciidoc | 1 +
.../src/content/kb/docs/java/index.asciidoc | 1 +
.../src/content/kb/docs/java/quickstart.asciidoc | 1 +
.../src/content/templates/tutorial.gsp | 12 +
7 files changed, 287 insertions(+)
diff --git a/netbeans.apache.org/src/content/kb/docs/contributing.asciidoc
b/netbeans.apache.org/src/content/kb/docs/contributing.asciidoc
new file mode 100644
index 0000000..3f6ce7a
--- /dev/null
+++ b/netbeans.apache.org/src/content/kb/docs/contributing.asciidoc
@@ -0,0 +1,272 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you 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.
+//
+
+
+= Tutorial Contribution Guidelines
+:jbake-type: tutorial
+:jbake-tags: tutorials
+:jbake-status: published
+:reviewed: 2019-01-25
+:toc: left
+:icons: font
+:toc-title:
+:description: Tutorial Contribution Guidelines
+:reviewed: 2019-01-25
+
+The Apache NetBeans Tutorials were included in the third donation from Oracle
to the Apache Software Foundation. Many of these tutorials need to be reviewed.
Everybody can help out in the review process. All you need is a web browser, a
GitHub account and a basic knowledge of link:https://asciidoctor.org/[AsciiDoc].
+
+This page describes some tips, tricks and conventions for reviewing tutorials
for Apache NetBeans.
+
+== The NetBeans Web Site
+
+The NetBeans website is written mainly in link:http://asciidoc.org/[AsciiDoc],
a way of creating technical components using plain text files.
+
+We then generate HTML for the web using Groovy Server Page templates (these
live in
https://github.com/apache/incubator-netbeans-website/tree/master/netbeans.apache.org/src/content/templates
). These templates (and some other stuff like SCSS) are responsible for the
layout of the web pages.
+
+NOTE: The generated HTML is responsive, this is, it can be correctly
visualized in mobile phones.
+
+=== Direct editing in GitHub
+
+All web pages can be edited directly in GitHub. To do so follow these
instructions:
+
+1. Click the "See this page in GitHub" link at the bottom of any page.
+
+image::images/contributing-link.png[title="Click the 'See this page in GitHub'
link to edit a page"]
+
+[start=2]
+2. You will then be redirected to GitHub. Once there click the "Edit this
file" button.
+
+image::images/contributing-button.png[title="Edit button in GitHub"]
+
+If you don't have edit permissions you always can clone the
link:https://github.com/apache/incubator-netbeans-website[website repository in
GitHub] and then edit the file in your own clone, and then submit that as a
Pull Request against the main Apache Repository.
+
+== AsciiDoc Conventions in Apache NetBeans
+
+=== License Header
+
+All `.asciidoc` pages must have a license header stating the Apache License
and the Apache Software Foundation ownership. The Apache license header is
included as an asciidoc comment, like so:
+
+[source, asciidoc]
+----
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you 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.
+//
+----
+
+
+
+=== The title
+
+All tutorials must start with a "Level 0" title with a single equal sign. This
will be the title of the page. You write a title like so:
+
+[source, asciidoc]
+----
+= This is a title
+----
+
+It is an error if there's any content _before_ the level 0 title (but for
comments). If you see any content above the title then please move it below the
title (that's called the "AsciiDoc Preamble").
+
+=== Metadata
+
+Immediately after the level 0 title, we add the metadata of the page, all the
"jbake-" entries are mandatory. Some others are commented below:
+
+[source, asciidoc]
+----
+:jbake-type: tutorial
+:jbake-tags: tutorials
+:jbake-status: published
+:reviewed: 2019-01-25
+:syntax: true
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:icons: font
+:description: NetBeans IDE Java Quick Start Tutorial - Apache NetBeans
+:keywords: Apache NetBeans, Tutorials, NetBeans IDE Java Quick Start Tutorial
+----
+
+This is a small description of the metadata:
+
+- `reviewed`: set this to the date the tutorial was reviewed, for instance,
2019-01-25.
+- `jbake-type`: use `tutorial` for tutorial pages, `wiki` for wiki pages,
`page` for simple pages.
+- `jbake-tags`: use `tutorials` for tutorials, feel free to any tags of your
liking (we should formalize this).
+- `jbake-status`: always set it to `published`
+- Set `syntax` to `true` if this page contains source code that has to be
syntax-highlighted. Please also add `source-highlighter` to `pygments`.
+- `toc` Set always to left.
+- `toc-title` Leave empty.
+- `icons` Set to `font` for adding support for FontAwesome icons.
+- `description`: set to something that describes the page. This is used for
SEO.
+- `keywords`: keywords describing the page. This is used for SEO.
+
+== The Content
+
+Write the rest of the page using plain AsciiDoc. See the AsciiDoctor Writer's
Guide for more information https://asciidoctor.org/docs/asciidoc-writers-guide/
+
+You can structure the content using sections. Start each section with a level
1 header, that must have at least two equal signs (but can have more for
subsections), like so:
+
+[source, asciidoc]
+----
+== This is a section header
+
+Some content here
+
+=== This is a subsection
+
+Some more stuff here
+----
+
+
+TIP: In general we should make the tutorials be less wordy, less long
paragraphs. Special Constructs and Best Practices.
+
+=== Inline screenshots and images
+
+Images related to a webpage are usually included in a `images/` subdirectory
close to the webpage.
+
+Screenshots should be at least 640px wide?? (what's a good size for retina
images?). PNG is preferred (isn't it?)
+
+Images in a table should be inlined, i.e., using the `single colon` image
construct, like so:
+
+[source, asciidoc]
+----
+image:images/image.png[]
+----
+
+=== Block images and screenshots
+
+Block images are inserted using the `image::` AsciiDoc construct, this is,
with two colons. These take a
+paragraph of their own. Example:
+
+[source, asciidoc]
+----
+image::images/image.png[title="This is the image caption"]
+----
+
+NOTE: Note the two colons for block images, and a single colon for inlined (in
the paragraph) images.
+
+
+=== Clickable screenshots
+
+Clickable screenshots are generated using a "[.feature]" tag above a paragraph
that contains the image. This allows us to have a small image (the focuses on a
part of the screenshot) that the user can click to see a larger image. The
AsciiDoc construct for these is like so:
+
+[source, asciidoc]
+----
+
+[.feature]
+--
+image::images/the-title-of-the-image-small.png[role="left", title="Click to
enlarge", link="images/the-title-of-the-image-big.png"]
+--
+----
+
+TIP: Be sure to add a newline before the `[.feature]` tag.
+
+=== Youtube videos
+
+Use the "video" asciidoc macro to embed youtube videos, like so:
+
+[source, asciidoc]
+----
+video::the-youtube-video-identifier[youtube, title="The title"]
+----
+
+where "the-youtube-video-identifier" is the id of the youtube video, for
instance `O8cwpEY1OAQ` is the identifier for
https://www.youtube.com/embed/O8cwpEY1OAQ
+
+=== Source code
+
+Use the plain asciidoc construct for source code excerpts (that is, four
slashes). Please the the "lang" attribute accordingly, for instance, for Java:
+
+[source, asciidoc]
+----
+ [source,java]
+ ----
+ System.out.println("Hello, world");
+ ----
+----
+
+Other languages are `html`, `xml`, `javascript`, `php`, `python`, `ruby`.
Remember to use the `:syntax: true` atribute in the metadata so that syntax
highlighting works.
+
+=== Numbered lists
+
+Numbered lists that have in-between paragraphs often restart numbering. So, for
+instance, you have item 1, item 2, then a paragraph and then the next item
+starts again at 1
+
+Remember that you can tell asciidoc to start a numbered list on a certain
number using the "start" tag, like so:
+
+[source, asciidoc]
+----
+1. This is the first item
+2. This is the second item
+
+Now we have a paragraph here, or an image or whatever
+
+[start=3]
+3. This is the third item
+----
+
+=== Admonitions (notes, tips)
+
+Use `NOTE:` and `TIP:` for admonitions. These must be in capital letters,
without any asterkisks around them:
+
+[source, asciidoc]
+----
+NOTE: This is a note
+----
+
+If you use these admonitions be sure to add the
+
+[source, asciidoc]
+----
+:icons: font
+----
+
+on the metadata of the page, so that admonitions have proper icons.
+
+=== Icons
+
+To use font awesome icons in your webpage include the `:icons: font` in the
metadata of the page.
+
+Then you can reference an icon using the name of the icon in the asciidoc icon
macro, like so:
+
+[source, asciidoc]
+----
+.icon:users[]
+----
+
+for a list of icons see https://fontawesome.com/icons?d=gallery
+
+=== New features
+
+If you need to include a new feature in the page then
+please request for it in our
link:http://netbeans.apache.org/community/mailing-lists.html[Dev Mailing List].
+
diff --git
a/netbeans.apache.org/src/content/kb/docs/images/contributing-button.png
b/netbeans.apache.org/src/content/kb/docs/images/contributing-button.png
new file mode 100644
index 0000000..79a5c81
Binary files /dev/null and
b/netbeans.apache.org/src/content/kb/docs/images/contributing-button.png differ
diff --git
a/netbeans.apache.org/src/content/kb/docs/images/contributing-link.png
b/netbeans.apache.org/src/content/kb/docs/images/contributing-link.png
new file mode 100644
index 0000000..69efcd0
Binary files /dev/null and
b/netbeans.apache.org/src/content/kb/docs/images/contributing-link.png differ
diff --git a/netbeans.apache.org/src/content/kb/docs/index.asciidoc
b/netbeans.apache.org/src/content/kb/docs/index.asciidoc
index c9b7baf..874affc 100644
--- a/netbeans.apache.org/src/content/kb/docs/index.asciidoc
+++ b/netbeans.apache.org/src/content/kb/docs/index.asciidoc
@@ -25,6 +25,7 @@
:icons: font
:toc-title:
:description: NetBeans Tutorials
+:reviewed: 2019-01-25
[.cards]
****
diff --git a/netbeans.apache.org/src/content/kb/docs/java/index.asciidoc
b/netbeans.apache.org/src/content/kb/docs/java/index.asciidoc
index d607483..d7fe93d 100644
--- a/netbeans.apache.org/src/content/kb/docs/java/index.asciidoc
+++ b/netbeans.apache.org/src/content/kb/docs/java/index.asciidoc
@@ -24,6 +24,7 @@
:toc: left
:toc-title:
:description: Java Tutorials
+:reviewed: 2019-01-25
This learning trail is focused on Java SE applications. A Java SE application
is an application written to the Java Platform, Standard Edition (Java SE). The
same unmodified Java SE applications can be run on almost any computer, whether
that computer uses the Microsoft Windows, Solaris, Linux, or OS X operating
systems. The key to this application portability is the Java Runtime
Environment, which is available free of charge for most operating systems,
including all of the ones mentione [...]
diff --git a/netbeans.apache.org/src/content/kb/docs/java/quickstart.asciidoc
b/netbeans.apache.org/src/content/kb/docs/java/quickstart.asciidoc
index b596665..2fd2e63 100644
--- a/netbeans.apache.org/src/content/kb/docs/java/quickstart.asciidoc
+++ b/netbeans.apache.org/src/content/kb/docs/java/quickstart.asciidoc
@@ -29,6 +29,7 @@
:toc-title:
:description: NetBeans IDE Java Quick Start Tutorial - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, NetBeans IDE Java Quick Start Tutorial
+:reviewed: 2019-01-25
Welcome to Apache NetBeans IDE!
diff --git a/netbeans.apache.org/src/content/templates/tutorial.gsp
b/netbeans.apache.org/src/content/templates/tutorial.gsp
index 12c716f..912710a 100644
--- a/netbeans.apache.org/src/content/templates/tutorial.gsp
+++ b/netbeans.apache.org/src/content/templates/tutorial.gsp
@@ -28,6 +28,18 @@
<%include "news.gsp"%>
<div class='grid-container main-content tutorial'>
<h1 class="sect0">${content.title}</h1>
+ <% if (content.reviewed == null) { %>
+ <div class="sectionbody">
+ <div class="admonitionblock note">
+ <table>
+ <tbody><tr>
+ <td class="icon"><i class="fa icon-note"
title="Note"></i></td>
+ <td class="content">This tutorial needs a review. You can <a
href="/kb/docs/contributing.html">help us review it.</a></td>
+ </tr></tbody>
+ </table>
+ </div>
+ </div>
+ <% } %>
${content.body}
<%include "tools.gsp"%>
</div>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@netbeans.apache.org
For additional commands, e-mail: commits-h...@netbeans.apache.org
For further information about the NetBeans mailing lists, visit:
https://cwiki.apache.org/confluence/display/NETBEANS/Mailing+lists
