docs: port over template from AddressBook-Level4

The following commits implement the documentation template in AddressBook-Level4: 686ec9ac9b9a17e5962c2341c08471e89d452d23..a1b29c20c825312a14ffe6b8242baee056cb5017 For consistency with AddressBook-Level4, port over those commits into this repo. This is done by running the following shell script: git fetch https://github.com/se-edu/addressbook-level4 master && git diff --binary 686ec9ac9b9a17e5962c2341c08471e89d452d23..a1b29c20c825312a14ffe6b8242baee056cb5017 >patch && git apply --3way --include=build.gradle --include='docs/images/*' --include='docs/stylesheets/*' --include='docs/templates/*' patch and fixing the conflicts in build.gradle.
zxjtan · Jul 5, 2018 · b6e0e9c · b6e0e9c
1 parent 7d1a71a
commit b6e0e9c
Show file tree

Hide file tree

Showing 10 changed files with 660 additions and 0 deletions.
diff --git a/build.gradle b/build.gradle
@@ -11,6 +11,10 @@ asciidoctor {
     sourceDir 'docs'
     outputDir "${buildDir}/docs"
 
+    options = [
+        template_dirs: [file("${sourceDir}/templates")],
+    ]
+
     attributes = [
         linkcss: true,
         stylesheet: 'gh-pages.css',
@@ -20,7 +24,15 @@ asciidoctor {
         sectlinks: true,
         idprefix: '',  // for compatibility with GitHub preview
         idseparator: '-',
+        'site-root': "${sourceDir}",  // must be the same as sourceDir, do not modify
+        'site-name': 'AddressBook-Level4',
+        'site-githuburl': 'https://github.com/se-edu/addressbook-level4',
+        'site-seedu': true,  // delete this line if your project is not a fork (not a SE-EDU project)
     ]
+
+    options['template_dirs'].each {
+        inputs.files fileTree(it)
+    }
 }
 
 // Copies stylesheets into the directory containing generated HTML files as

diff --git a/docs/images/SeEduLogo.png b/docs/images/SeEduLogo.png
diff --git a/docs/stylesheets/gh-pages.css b/docs/stylesheets/gh-pages.css
@@ -17,3 +17,198 @@
     padding-bottom: 0;
     padding-top: 0;
 }
+
+/* Overrides for asciidoctor.css */
+
+a {
+    color: #0074c7;
+}
+
+h1,
+#content h1 > a.link,
+h2,
+h2 > a.link,
+h3,
+h3 > a.link,
+#toctitle,
+#toctitle > a.link,
+.sidebarblock > .content > .title,
+.sidebarblock > .content > .title > a.link,
+h4,
+h4 > a.link,
+h5,
+h5 > a.link,
+h6,
+h6 > a.link {
+    color: #e46c0a;
+}
+
+.subheader,
+.admonitionblock td.content > .title,
+.audioblock > .title,
+.exampleblock > .title,
+.imageblock > .title,
+.listingblock > .title,
+.literalblock > .title,
+.stemblock > .title,
+.openblock > .title,
+.paragraph >.title,
+.quoteblock > .title,
+table.tableblock > .title,
+.verseblock > .title,
+.videoblock > .title,
+.dlist > .title,
+.olist > .title,
+.ulist > .title,
+.qlist > .title,
+.hdlist > .title {
+    color: rgb(197, 90, 17);
+}
+
+@media screen {
+    #footer {
+        background-color: #f6f6f6;
+        border-top: 1px #d2d2d2 solid;
+        border-bottom: 1px #d2d2d2 solid;
+        font-family: "Open Sans", "DejaVu Sans", sans-serif;
+    }
+
+    #footer-text {
+        color: #595959;
+        line-height: 1;
+    }
+}
+
+/* Utilities */
+
+.container {
+    width: 100%;
+    max-width: 62.5rem;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+/* Colors */
+
+.bg-light {
+    background-color: #f8f9fa;
+}
+
+.bg-lighter {
+    background-color: #fbfbfb;
+}
+
+
+/* Navbar */
+
+.navbar {
+    display: flex;
+    flex-wrap: nowrap;
+    justify-content: center;
+    font-family: "Open Sans", "DejaVu Sans", sans-serif;
+    font-size: 1rem;
+    padding: 0px 1rem;
+}
+
+.navbar-lg {
+    font-size: 1.3rem;
+}
+
+.navbar-light {
+    border-bottom: 1px #d2d2d2 solid;
+}
+
+.navbar a {
+    text-decoration: none;
+}
+
+.navbar-light a {
+    color: #595959;
+}
+
+.navbar-light a:hover,
+.navbar-light a:focus {
+    color: #000000;
+}
+
+.navbar a.active,
+.navbar a.active:hover,
+.navbar a.active:focus {
+    font-weight: bold;
+}
+
+.navbar-light a.active,
+.navbar-light a.active:hover,
+.navbar-light a.active:focus {
+    color: #000000;
+}
+
+.navbar-light .nav-link {
+    border-bottom: 2px transparent solid;
+}
+
+.navbar-light .nav-link.active {
+    border-bottom: 2px #e46c0a solid;
+}
+
+.navbar-lg .nav-link.active {
+    border-bottom: 0;
+}
+
+.navbar > .container {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+}
+
+.navbar-brand {
+    display: inline-block;
+    margin-right: 1rem;
+    padding: 0.8125rem 0rem;
+    padding-left: 0.9375rem;
+    font-size: 1.25rem;
+}
+
+.navbar-brand img {
+    height: 1.4rem;
+    margin: 0rem 0.4rem;
+    padding: 0;
+    vertical-align: middle;
+}
+
+.navbar-lg .navbar-brand {
+    font-size: 1.7rem;
+}
+
+.navbar-lg .navbar-brand img {
+    height: 2.3rem;
+}
+
+.navbar-nav {
+    display: flex;
+    flex-wrap: wrap;
+    flex-grow: 1;
+    align-items: center;
+    margin: 0px;
+    padding: 0px;
+    list-style: none;
+    line-height: inherit;
+}
+
+.nav-link {
+    display: block;
+    margin: 0px;
+    border: 0px;
+    padding: 1rem 1rem;
+}
+
+/* Do not display site header on print mediums */
+@media print {
+    #seedu-header {
+        display: none;
+    }
+
+    #site-header {
+        display: none;
+    }
+}
diff --git a/docs/templates/LICENSE b/docs/templates/LICENSE
@@ -0,0 +1,24 @@
+This directory contains code from the Asciidoctor Project.
+(https://asciidoctor.org/)
+
+MIT License
+
+Copyright (C) 2012-2018 Dan Allen, Ryan Waldron and the Asciidoctor Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
diff --git a/docs/templates/_footer.html.slim b/docs/templates/_footer.html.slim
@@ -0,0 +1,12 @@
+/ NOTE: You must restart the gradle daemon after modifying any template file for the changes to take effect.
+#footer
+  .container
+    #footer-text
+      - if attr? :revnumber
+        |#{attr 'version-label'} #{attr :revnumber}
+      - if attr? :revnumber && (attr? 'last-update-label')
+        br
+      - if attr? 'last-update-label'
+        |#{attr 'last-update-label'} #{attr :docdatetime}
+    - unless (docinfo_content = (docinfo :footer)).empty?
+      =docinfo_content
diff --git a/docs/templates/_footnotes.html.slim b/docs/templates/_footnotes.html.slim
@@ -0,0 +1,7 @@
+/ NOTE: You must restart the gradle daemon after modifying any template file for the changes to take effect.
+#footnotes
+  hr
+  - footnotes.each do |fn|
+    .footnote id=(footnote_id fn.index)
+      a href="##{footnoteref_id fn.index}" =fn.index
+      |. #{fn.text}
diff --git a/docs/templates/_header.html.slim b/docs/templates/_header.html.slim
@@ -0,0 +1,76 @@
+/ NOTE: You must restart the gradle daemon after modifying any template file for the changes to take effect.
+- if !(attr? 'no-site-header') && (attr? 'site-seedu')
+  #seedu-header
+    nav.navbar.navbar-lg.navbar-light.bg-lighter
+      .container
+        a.navbar-brand href='https://se-edu.github.io/'
+          img src=(site_url 'images/SeEduLogo.png') alt='SE-EDU'
+        ul.navbar-nav
+          li.nav-item
+            a.nav-link href='https://se-edu.github.io/addressbook-level1' AB-1
+          li.nav-item
+            a.nav-link href='https://se-edu.github.io/addressbook-level2' AB-2
+          li.nav-item
+            a.nav-link href='https://se-edu.github.io/addressbook-level3' AB-3
+          li.nav-item
+            a.nav-link.active href=(site_url 'index.html') AB-4
+          li.nav-item
+            a.nav-link href='https://se-edu.github.io/collate' Collate
+          li.nav-item
+            a.nav-link href='https://se-edu.github.io/se-book' Book
+          li.nav-item
+            a.nav-link href='https://se-edu.github.io/learningresources' Resources
+
+- if !(attr? 'no-site-header')
+  #site-header
+    nav.navbar.navbar-light.bg-light
+      .container
+        - if attr? 'site-name'
+            a.navbar-brand href=(site_url 'index.html') =(attr 'site-name')
+        ul.navbar-nav
+          li.nav-item
+            =nav_link('UserGuide', 'UserGuide.html', 'User Guide')
+          li.nav-item
+            =nav_link('DeveloperGuide', 'DeveloperGuide.html', 'Developer Guide')
+          - if attr? 'site-seedu'
+            li.nav-item
+              =nav_link('LearningOutcomes', 'LearningOutcomes.html', 'LOs')
+          li.nav-item
+            =nav_link('AboutUs', 'AboutUs.html', 'About Us')
+          li.nav-item
+            =nav_link('ContactUs', 'ContactUs.html', 'Contact Us')
+          - if attr? 'site-githuburl'
+            li.navitem
+              a.nav-link href=(attr 'site-githuburl')
+                span.fa.fa-github.fa-lg aria-hidden='true'
+                | &nbsp;View on GitHub
+
+/ AsciiDoc leaves an empty header div even if there's no doctitle
+#header
+  - if has_header?
+    - unless notitle
+      h1 =header.title
+    - if [:author, :revnumber, :revdate, :revremark].any? {|a| attr? a }
+      .details
+        - if attr? :author
+          span.author#author =(attr :author)
+          br
+          - if attr? :email
+            span.email#email =sub_macros(attr :email)
+            br
+          - if (authorcount = (attr :authorcount).to_i) > 1
+            - (2..authorcount).each do |idx|
+              span.author id="author#{idx}" =(attr "author_#{idx}")
+              br
+              - if attr? "email_#{idx}"
+                span.email id="email#{idx}" =sub_macros(attr "email_#{idx}")
+        - if attr? :revnumber
+          span#revnumber #{((attr 'version-label') || '').downcase} #{attr :revnumber}#{',' if attr? :revdate}
+          '
+        - if attr? :revdate
+          span#revdate =attr :revdate
+        - if attr? :revremark
+          br
+          span#revremark =(attr :revremark)
+  - if (attr? :toc) && (attr? 'toc-placement', 'auto')
+    include _toc.html
diff --git a/docs/templates/_toc.html.slim b/docs/templates/_toc.html.slim
@@ -0,0 +1,5 @@
+/ NOTE: You must restart the gradle daemon after modifying any template file for the changes to take effect.
+#toc class=(attr 'toc-class', 'toc')
+  #toctitle =(attr 'toc-title')
+  / Renders block_outline.html.
+  = converter.convert document, 'outline'
diff --git a/docs/templates/document.html.slim b/docs/templates/document.html.slim
@@ -0,0 +1,29 @@
+/ NOTE: You must restart the gradle daemon after modifying any template file for the changes to take effect.
+doctype 5
+html lang=(attr :lang, 'en' unless attr? :nolang)
+  head
+    meta charset=(attr :encoding, 'UTF-8')
+    /[if IE]
+      meta http-equiv="X-UA-Compatible" content="IE=edge"
+    meta name='viewport' content='width=device-width, initial-scale=1.0'
+    meta name='generator' content="Asciidoctor #{attr 'asciidoctor-version'}"
+    = html_meta_if 'application-name', (attr 'app-name')
+    = html_meta_if 'author', (attr :authors)
+    = html_meta_if 'copyright', (attr :copyright)
+    = html_meta_if 'description', (attr :description)
+    = html_meta_if 'keywords', (attr :keywords)
+    title=((doctitle sanitize: true) || (attr 'untitled-label'))
+    = styles_and_scripts
+    - unless (docinfo_content = docinfo).empty?
+      =docinfo_content
+  body(
+    id=id
+    class=[(attr :doctype), ("#{attr 'toc-class'} toc-#{attr 'toc-position', 'left'}" if (attr? 'toc-class') && (attr? :toc) && (attr? 'toc-placement', 'auto'))]
+    style=style_value(max_width: (attr 'max-width')))
+    - unless noheader
+      include _header.html
+    #content =content
+    - unless !footnotes? || (attr? :nofootnotes)
+      include _footnotes.html
+    - unless nofooter
+      include _footer.html