guacamole-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mjum...@apache.org
Subject [2/2] incubator-guacamole-website git commit: Add README.md and exclude from Jekyll build.
Date Tue, 26 Apr 2016 19:57:02 GMT
Add README.md and exclude from Jekyll build.


Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/commit/c47a2e19
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/tree/c47a2e19
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/diff/c47a2e19

Branch: refs/heads/master
Commit: c47a2e19a6b779a54240ed37df9032c31ac39630
Parents: 30834f4
Author: Michael Jumper <mjumper@apache.org>
Authored: Tue Apr 26 12:56:46 2016 -0700
Committer: Michael Jumper <mjumper@apache.org>
Committed: Tue Apr 26 12:56:46 2016 -0700

----------------------------------------------------------------------
 README.md   | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 _config.yml |   1 +
 2 files changed, 150 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/c47a2e19/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1b53acd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,149 @@
+The Apache Guacamole website
+============================
+
+This repository contains the source for the website of Apache Guacamole, a
+clientless remote desktop solution currently undergoing incubation at the
+Apache Incubator.
+
+The website itself is completely static, being automatically generated by
+[Jekyll](https://jekyllrb.com/) prior to deployment. The content of the website
+is written in a mixture of HTML and Markdown, with dynamic portions written
+using [liquid templating](https://jekyllrb.com/docs/templates/). Templated
+content is interpreted only a build time, with the final result being
+completely static.
+
+To facilitate ease of development and testing, this repository also contains a
+build script, `build.sh`, the usage of which is documented below.
+
+Table of contents
+-----------------
+
+* [Repository structure](#repository-structure)
+* [Build prerequisites](#build-prerequisites)
+* [Testing changes locally](#testing-changes-locally)
+* [Publishing changes](#publishing-changes)
+
+Repository structure
+--------------------
+
+In addition to the `LICENSE` and `NOTICE` files required of any proper Apache-
+licensed project, the repository contains the following critical files:
+
+| Filename      | Description
+| ------------- | -----------
+| `_config.yml` | Configuration information controlling the Jekyll build.  This is a standard
Jekyll file. See: [Jekyll directory structure](https://jekyllrb.com/docs/structure/)
+| `build.sh`    | The website build script (usage documented below).
+| `doc/`        | Per-release documentation for Apache Guacamole. This directory contains
one subdirectory per release, where each subdirectory contains the overall manual (`.../gug/`)
API documentation for each part of the Guacamole core (`.../libguac/`, `.../guacamole-common/`,
etc.). Files in this directory are not interpreted by Jekyll, as there are far too many files
for this to be reasonable. They are instead copied into place by the `build.sh` script.
+| `images/`     | Images which are referenced within the website HTML and CSS.
+| `pub/`        | Miscellaneous public files, such as test scripts. The test scripts in this
directory have historically been shared to users to help with debugging.
+| `styles/`     | All CSS files referenced by the website HTML.
+| `_includes/`  | Common HTML fragments used by Jekyll and referenced in other templates,
such as the website header and footer. These *must* be HTML only. This is a standard Jekyll
directory. See: [Jekyll directory structure](https://jekyllrb.com/docs/structure/)
+| `_layouts/`   | Templates describing the structure of different types of content. This
is a standard Jekyll directory. See: [Jekyll directory structure](https://jekyllrb.com/docs/structure/)
+| `_links/`     | Documents which contain metadata describing the links which should appear
in the site navigation menu. The documents here are completely empty except for the metadata.
+| `_releases`   | Release notes for Guacamole releases, including metadata describing the
files and documentation associated with those releases.
+
+Build prerequisites
+-------------------
+
+The build depends entirely on Jekyll, thus this must be installed first. If you
+do not yet have Jekyll installed, please see [Jekyll's own installation
+instructions](https://jekyllrb.com/docs/installation/) to get started.
+
+Beyond Jekyll, you will also need:
+
+* A POSIX-compliant implementation of `sh` (to run `build.sh`)
+* git (to clone this repository and to publish changes)
+* `mktemp` (used by `build.sh` when staging changes prior to publishing)
+
+The `build.sh` script will check whether the required programs are installed,
+and will fail early with an appropriate message if a required program cannot be
+found.
+
+The build script handles three primary variations of common build tasks:
+
+1. The build itself, when invoked as `./build.sh`. This invokes Jekyll and recursively copies
the `doc/` (part of the website source) and `_site/` (generated by Jekyll during the build)
to the `content/` directory.
+2. Serving a local copy of the website, when invoked as `./build.sh PORT`.
+3. Staging local changes for commit to the special "asf-git" branch, when invoked as `./build.sh
stage`. Once changes are committed and pushed to "asf-git", the public website will be updated
by the ASF's gitpubsub.
+
+Testing changes locally
+-----------------------
+
+To test your changes to the website, you can either invoke `./build.sh` to build a static
copy of the site to the `content/` subdirectory, or invoke `./build.sh PORT` (where `PORT`
a TCP port number) to both build the static copy of the site *and* run Ruby's web server to
serve `content/` locally at the given port:
+
+    $ ./build.sh 8080
+    Configuration file: /home/mjumper/apache-guacamole/incubator-guacamole-website/_config.yml
+                Source: /home/mjumper/apache-guacamole/incubator-guacamole-website
+           Destination: /home/mjumper/apache-guacamole/incubator-guacamole-website/_site
+     Incremental build: disabled. Enable with --incremental
+          Generating...
+                        done in 0.563 seconds.
+     Auto-regeneration: disabled. Use --watch to enable.
+    Copying "doc/" and built site to "content/" ...
+    Done. Full site is now within the "content/" directory.
+    [2016-04-26 12:35:36] INFO  WEBrick 1.3.1
+    [2016-04-26 12:35:36] INFO  ruby 2.1.7 (2015-08-18) [x86_64-linux]
+    [2016-04-26 12:35:36] INFO  WEBrick::HTTPServer#start: pid=18927 port=8080
+
+When done testing your local changes, press `Ctrl`&nbsp;+&nbsp;`C` to stop the
+web server and return to the shell.
+
+Publishing changes
+------------------
+
+Changes to the website are published using Apache's
+[gitpubsub](https://blogs.apache.org/infra/entry/git_based_websites_available)
+which relies on a special branch called "asf-git" containing *all website
+content* within a directory called `content/`.
+
+In the Apache Guacamole website repository, the "asf-git" branch is an "orphan"
+branch. The branch has no commits in common with the "master" branch and
+consists solely of the `content/` subdirectory. Updating the website thus
+involves:
+
+1. Making and testing your changes locally
+2. Replacing the entire contents of the `content/` directory within "asf-git"
+   with the newly-generated `content/` directory.
+
+The `build.sh` script can take care of all this for you when invoked as
+`./build.sh stage`:
+
+    $ ./build.sh stage
+    Configuration file: /home/mjumper/apache-guacamole/incubator-guacamole-website/_config.yml
+                Source: /home/mjumper/apache-guacamole/incubator-guacamole-website
+           Destination: /home/mjumper/apache-guacamole/incubator-guacamole-website/_site
+     Incremental build: disabled. Enable with --incremental
+          Generating...
+                        done in 0.568 seconds.
+     Auto-regeneration: disabled. Use --watch to enable.
+    Copying "doc/" and built site to "content/" ...
+    Done. Full site is now within the "content/" directory.
+    Switched to branch 'asf-git'
+    Removing README.md
+    Removing _site/
+    Content staged for commit. Use git to commit the results when ready.
+    NOTE: The build.sh script will no longer exist. To serve the staged
+    contents, run:
+
+        ruby -run -e httpd content/ -p PORT
+
+    where PORT is the port number where the HTTP server should listen.
+    $
+
+At this point, you will be on the "asf-git" branch and the current directory
+will contain only the `content/` subdirectory:
+
+    $ ls
+    content
+    $
+
+Keep in mind that the new content is only *staged* for commit. It has not yet
+been committed. Once you have verified that the staged content is as expected,
+commit your changes (along with a useful commit message describing the changes
+at a high level) using `git commit` and publish the update using
+`git push origin`.
+
+If you wish to unstage your changes, use `git reset --hard HEAD` to return to
+the original state of "asf-git", wiping out any local modifications made by
+`build.sh`. You can then return to whichever branch you were working on with
+`git checkout`.
+

http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/c47a2e19/_config.yml
----------------------------------------------------------------------
diff --git a/_config.yml b/_config.yml
index 1c66f79..c21c2d0 100644
--- a/_config.yml
+++ b/_config.yml
@@ -23,6 +23,7 @@ title: Apache Guacamole
 # Build settings
 markdown: kramdown
 exclude:
+    - README.md
     - build.sh
     - content
     - doc


Mime
View raw message