Merge pull request #179 from guicho271828/cli-preview-done-in-staging

Cli preview done in staging

README.md

@@ -44,69 +44,77 @@ testing is primarily done on [SBCL](http://www.sbcl.org/) and [CCL](http://ccl.c
 Step 1: Install this library.
 
 With [Roswell](https://roswell.github.io/),
-``` sh
+```
 $ ros install coleslaw
 $ export PATH="$HOME/.roswell/bin:$PATH" # If you haven't done this before
-```
-
 or
-
+CL-USER> (ql:quickload :coleslaw-cli)
-``` lisp
-(ql:quickload :coleslaw-cli)
 ```
 
-
 Step 2: Initialize your blog repository.
 
-``` sh
+``` 
 $ mkdir yourblog ; cd yourblog
 $ git init
-$ coleslaw setup
+$ coleslaw setup              # or
-```
+CL-USER> (coleslaw-cli:setup)
-``` lisp
-(coleslaw-cli:setup)
 ```
 
+`coleslaw setup` / `(coleslaw-cli:setup)` will generate a `.coleslawrc` file in
+the current directory, which contains the configuration of the static website.
+
 Step 3: Write a post file in the current directory.
 The file should contain a certain metadata, so use the `coleslaw new` command,
 which instantiates a correct file for you.
 
-``` sh
+```
 $ coleslaw new
 Created a post 2017-11-06.post .
-```
+# or 
-``` lisp
+CL-USER> (coleslaw-cli:new "post")
-(coleslaw-cli:new "post")
+Created a post 2017-11-06.post .
 ```
 
 Step 4: Generate the site from those post files.
-The result goes to the `deploy/` subdirectory.
+The result goes to the *staging directory* specified in the `.coleslawrc` file.
+The staging directory is `/tmp/coleslaw/` by default.
 
-``` sh
-$ coleslaw
 ```
-``` lisp
+$ coleslaw          # or
-(coleslaw-cli:generate)
+$ coleslaw generate # or
+$ coleslaw stage    # or
+CL-USER> (coleslaw-cli:generate) ; or
+CL-USER> (coleslaw-cli:stage)    ; --- these are all aliases
 ```
 
-Step 5: You can also launch a server...
+Step 5: You can launch a web server to check the result on a browser.
+(Running a webserver sometimes has a benefit over just opening an html file,
+e.g. the relative links behaves differently on a file:/// protocol)
 
-``` sh
-$ coleslaw preview
 ```
-``` lisp
+$ coleslaw preview     # or
-(coleslaw-cli:preview)
+CL-USER> (coleslaw-cli:preview)
 ```
 
 Step 6: and watch the file system to automatically regenerate the site!
 
-``` sh
+```
 $ coleslaw watch          # or even better,
-$ coleslaw watch-preview 
+$ coleslaw watch-preview  # or, on REPL,
+CL-USER> (coleslaw-cli:watch)      ;; watch-preview does not work on REPL right now
 ```
-``` lisp
+
-(coleslaw-cli:watch)      ;; watch-preview does not work on REPL right now
+Step 7: When you think your article is publishable, run
+
 ```
+$ coleslaw deploy             # or
+CL-USER> (coleslaw-cli:deploy)
+```
+
+To move the contents in the staging dir to the deploy dir.
+By default, this deploy command uses `rsync` to sync the directories,
+where the deploy dir could be a remote directory on the server which is running your website.
+By using a plugin, you can customize this behavior e.g. running the deploy on gh-pages.
 
 For further customization, e.g. adding a new plugin, developing a new plugin, changing the deploy option, or creating a new theme,
 see the [config docs](docs).

cli/cli.lisp

@@ -8,7 +8,9 @@
    #:preview
    #:watch
    #:watch-preview
-   #:help))
+   #:help
+   #:stage
+   #:deploy))
   
 (in-package :coleslaw-cli)
 
@@ -117,9 +119,15 @@ Excerpt separator is `<!--more-->` by default.
            path))))))
 
 (defun generate ()
-  (coleslaw:main *default-pathname-defaults*))
+  (stage))
 
-(defun preview (&optional (path (getf (read-rc) :deploy-dir)))
+(defun stage ()
+  (coleslaw:main *default-pathname-defaults* :deploy nil))
+
+(defun deploy ()
+  (coleslaw:main *default-pathname-defaults* :deploy t))
+
+(defun preview (&optional (path (getf (read-rc) :staging-dir)))
   ;; clack depends on the global binding of *default-pathname-defaults*.
   (let ((oldpath *default-pathname-defaults*))
     (unwind-protect
@@ -212,10 +220,12 @@ Command Line Syntax:
 coleslaw setup [NAME]                --- Sets up a new .coleslawrc file in the current directory.
 coleslaw copy-theme THEME [TARGET]   --- Copies the installed THEME in coleslaw to the current directory with a different name TARGET.
 coleslaw new [TYPE] [NAME]           --- Creates a new content file with the correct format. TYPE defaults to 'post', NAME defaults to the current date.
-coleslaw generate                    --- Generates the static html according to .coleslawrc .
+coleslaw stage                       --- Generates the static html in the staging dir.
-coleslaw preview [DIRECTORY]         --- Runs a preview server at port 5000. DIRECTORY defaults to the deploy directory (described in .coleslawrc).
+coleslaw generate                    --- Alias to `coleslaw stage`.
+coleslaw deploy                      --- Generates the static html in the staging dir, then publish it to the deploy dir.
+coleslaw preview [DIRECTORY]         --- Runs a preview server at port 5000. DIRECTORY defaults to the staging directory.
 coleslaw watch [DIRECTORY]           --- Watches the given directory and generates the site when changes are detected. Defaults to the current directory.
-coleslaw                             --- Shorthand of 'coleslaw generate'.
+coleslaw                             --- Alias to `coleslaw stage`.
 coleslaw -h                          --- Show this help
 
 Corresponding REPL commands are available in coleslaw-cli package.
@@ -225,7 +235,9 @@ Corresponding REPL commands are available in coleslaw-cli package.
   (coleslaw-cli:setup            &optional name)
   (coleslaw-cli:copy-theme theme &optional target)
   (coleslaw-cli:new              &optional type name)
+  (coleslaw-cli:stage)
   (coleslaw-cli:generate)
+  (coleslaw-cli:deploy)
   (coleslaw-cli:preview &optional directory)
   (coleslaw-cli:watch   &optional directory)
 ```
@@ -279,7 +291,13 @@ Examples:
      (apply #'watch-preview rest))
     ((list* "new" rest)
      (apply #'new rest))
-    ((or nil (list "generate"))
+    ((list* "generate" rest)
+     (apply #'generate rest))
+    ((list* "stage" rest)
+     (apply #'stage rest))
+    ((list* "deploy" rest)
+     (apply #'deploy rest))
+    (nil
      (generate))
     ((list* "copy-theme" rest)
      (apply #'copy-theme rest))

src/coleslaw.lisp

@@ -3,16 +3,19 @@
 (defvar *last-revision* nil
   "The git revision prior to the last push. For use with GET-UPDATED-FILES.")
 
-(defun main (repo-dir &optional oldrev)
+(defun main (repo-dir &key oldrev (deploy t))
-  "Load the user's config file, then compile and deploy the blog stored
+  "Load the user's config file, compile the blog in REPO-DIR into STAGING-DIR,
-in REPO-DIR. Optionally, OLDREV is the revision prior to the last push."
+ and optionally deploy the blog to DEPLOY-DIR.
+  OLDREV -- the git revision prior to the last push.
+  DEPLOY -- when non-nil, perform the deploy. (default: t)"
   (load-config repo-dir)
   (setf *last-revision* oldrev)
   (load-content)
   (compile-theme (theme *config*))
   (let ((dir (staging-dir *config*)))
     (compile-blog dir)
-    (deploy dir)))
+    (when deploy
+      (deploy dir))))
 
 (defun load-content ()
   "Load all content stored in the blog's repo."

tests/cli.lisp

@@ -11,7 +11,7 @@
   (coleslaw-cli:setup)
   (let ((file (coleslaw-cli:new)))
     (ok (probe-file file)))
-  (coleslaw-cli:generate)
+  (coleslaw-cli:deploy)
   (print (format nil "~adeploy/index.html" *default-pathname-defaults*))
   (ok (probe-file (format nil "~adeploy/index.html" *default-pathname-defaults*))))