Merge pull request #334 from ExaWorks/revamp_web_infrastructure

Revamp web infrastructure

Author: hategan

Makefile

@@ -46,7 +46,7 @@ docs:
 .PHONY: web-docs
 web-docs:
 	rm -rf docs/.generated
-	sphinx-build -W -b html -D html_theme='cloud' docs docs/.web-build/
+	sphinx-build -W -b html -D html_theme='cloud' -D templates_path='_templates' docs docs/.web-build/
 
 .PHONY: style
 style:

README-dev.md

@@ -45,19 +45,26 @@ automatically:
     ```
 
 Make sure that `build.sh` is called from the main directory. The output will
-be in `web-build`. You are likely going to need to load it through a web
-server. A simple way to do so is:
+be in `web-build`.
+
+3. Render the web site and themed documentation, which can be done using Jekyll.
+To install Jekyll, follow these
+[instructions](https://jekyllrb.com/docs/installation/). Then run
 
     ```
-    cd web-build
-    python -m http.server <port>
+    web/serve.sh
     ```
 
-where `<port>` is a port number to start the HTTP server on.
+which will output something like this:
+```
+...
+    Server address: http://127.0.0.1:4000/psij-python/
+  Server running... press ctrl-c to stop.
+```
 
-When developing the web site, a convenient script is `web/watch.sh`, which can
-monitor the source directories and re-build when files are modified. This
-requires `inotify` which may or may not be available on your platform.
+Pointing your web browser to the URL printed by Jekyll will show the PSI/J
+web site. The themed documentation will be found under the "Documentation"
+tab.
 
 
 ### Release process

docs/_templates/layout.html

@@ -0,0 +1,34 @@
+{%- extends "cloud/layout.html" -%}
+
+{# We are not processing the output of these pages through Jekyll, so
+   we need to set the variables referenced in the includes. #}
+{% set site = {"baseurl": "/psij-python"} %}
+
+{% block scripts %}
+    {% include "../../web/_includes/head.html" %}
+    
+    {{ super() }}
+{% endblock %}
+
+{% block header %}
+    <v-app id="psij-app">
+        {% include "../../web/_includes/menu.html" %}
+        {{ super() }}
+{% endblock %}
+
+{% block footer %}
+        {{ super() }}
+        
+        {% include "../../web/_includes/footer.html" %}
+    </v-app>
+    
+    {# Same as above #}
+    {% set page = {"tab": 2} %}
+    {% include "../../web/_includes/vueinit.html" %}
+    
+
+{% endblock %}
+
+
+{% block sidebartoggle %}
+{% endblock %}

docs/_templates/searchbox.html

@@ -0,0 +1,18 @@
+{#
+    searchbox.html
+    ~~~~~~~~~~~~~~~~~~~~
+
+    Replaces basic/searchbox.html because vue.js does not like <script> without the type attribute
+#}
+{%- if pagename != "search" and builder != "singlehtml" %}
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">{{ _('Quick search') }}</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="{{ pathto('search') }}" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
+      <input type="submit" value="{{ _('Go') }}" />
+    </form>
+    </div>
+</div>
+<script type="application/javascript">$('#searchbox').show(0);</script>
+{%- endif %}

web/.gitignore

@@ -0,0 +1,5 @@
+_site
+.sass-cache
+.jekyll-cache
+.jekyll-metadata
+vendor

web/.nojekyll

@@ -0,0 +1,11 @@
+---
+permalink: /404.html
+layout: default
+---
+
+<div class="container">
+  <h1>404</h1>
+
+  <p><strong>Page not found :(</strong></p>
+  <p>The requested page could not be found.</p>
+</div>

web/404.html

@@ -0,0 +1,33 @@
+source "https://rubygems.org"
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+gem "jekyll", "~> 4.3.1"
+# This is the default theme for new Jekyll sites. You may change this to anything you like.
+gem "minima", "~> 2.5"
+# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+# uncomment the line below. To upgrade, run `bundle update github-pages`.
+# gem "github-pages", group: :jekyll_plugins
+# If you have any plugins, put them here!
+group :jekyll_plugins do
+  gem "jekyll-feed", "~> 0.12"
+end
+
+# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+# and associated library.
+platforms :mingw, :x64_mingw, :mswin, :jruby do
+  gem "tzinfo", ">= 1", "< 3"
+  gem "tzinfo-data"
+end
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
+
+# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
+# do not have a Java counterpart.
+gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]

web/Gemfile

@@ -0,0 +1,47 @@
+PSI/J Web Site
+==============
+
+The web site uses Jekyll, which is a Ruby tool for static page
+templating/generation. It is the tool used by Github Pages, so
+it is readily deployable there *before* running Jekyll.
+
+The web site also builds the documentation with a custom theme
+that allows the Sphinx output to be directly integrated into the
+main web site.
+
+Building
+========
+
+All operations are to be done from the *root directory* of the 
+PSI/J repository.
+
+ 1. Install the packages required to build the documentation 
+ (this step is only needed once):
+ 
+    ```bash
+    $ sudo pip install -r requirements-docs.txt
+    ```
+
+ 2. Install Jekyll (see [Jekyll Installation](https://jekyllrb.com/docs/installation/) - also a one-time operation).
+
+ 3. Run the build script, which will build the documentation, process
+ files in the `web` directory, and generate the output in `web-build`:
+ 
+    ```bash
+    $ web/build.sh
+    ```
+ 4. Run the Jekyll server with the script provided:
+ 
+    ```bash
+    $ web/serve.sh
+    ```
+    
+You should then see something like:
+```
+...
+    Server address: http://127.0.0.1:4000/psij-python/
+  Server running... press ctrl-c to stop.
+```
+
+You can then point your browser to `http://127.0.0.1:4000/psij-python` to
+see the rendered web site.

web/README.md

@@ -0,0 +1,57 @@
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your whole blog, values
+# which you are expected to set up once and rarely edit after that. If you find
+# yourself editing this file very often, consider using Jekyll's data files
+# feature for the data you need to update frequently.
+#
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
+#
+# If you need help with YAML syntax, here are some quick references for you:
+# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
+# https://learnxinyminutes.com/docs/yaml/
+#
+# Site settings
+# These are used to personalize your new site. If you look in the HTML files,
+# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
+# You can create any custom variable you would like, and they will be accessible
+# in the templates via {{ site.myvariable }}.
+
+title: "PSI/J - Python"
+email: [email protected]
+description: >- # this means to ignore newlines until "baseurl:"
+  Portable Submission Interface for Jobs
+  A Python abstraction layer over cluster schedulers
+baseurl: "/psij-python" # the subpath of your site, e.g. /blog
+url: "" # the base hostname & protocol for your site, e.g. http://example.com
+twitter_username: jekyllrb
+github_username:  jekyll
+
+# Build settings
+theme: minima
+plugins:
+  - jekyll-feed
+
+# Exclude from processing.
+# The following items will not be processed, by default.
+# Any item listed under the `exclude:` key here will be automatically added to
+# the internal "default list".
+#
+# Excluded items can be processed by explicitly listing the directories or
+# their entries' file path in the `include:` list.
+#
+# exclude:
+#   - .sass-cache/
+#   - .jekyll-cache/
+#   - gemfiles/
+#   - Gemfile
+#   - Gemfile.lock
+#   - node_modules/
+#   - vendor/bundle/
+#   - vendor/cache/
+#   - vendor/gems/
+#   - vendor/ruby/
+
+include:
+    - "**"