Add hugo DEV binary download to the Makefile; Update docs

8 years ago · d44632a929
parent 343c10ba2f
commit d44632a929
4 changed files with 72 additions and 41 deletions
--- a/.travis.yml
+++ b/.travis.yml
@ -18,7 +18,7 @@ install:
  - export EMACS=/tmp/emacs/bin/emacs
  - $EMACS --version
 script:
-  - make doc_md doc_gh EMACS=${EMACS} # Just ensure that "make doc_md" and "make doc_gh" don't fail for any reason.. this is *not* used to do Org->Markdown doc conversion using Travis.
+  - make doc EMACS=${EMACS} # Just ensure that "make doc" doesn't fail for any reason.. this is *not* used to do Org->Markdown doc conversion using Travis.
  - make test EMACS=${EMACS}
  - make vcheck EMACS=${EMACS}
 notifications:
--- a/CONTRIBUTING.org
+++ b/CONTRIBUTING.org
@ -15,6 +15,9 @@ for your future contributions to Emacs too!
 1. Clone this repo.
 2. Add/edit documentation to =doc/ox-hugo-manual.org=.
 3. Run =make doc=.
+   - This generates the Markdown files for the =ox-hugo= documentation
+     site and the .org files like =README.org= and =CONTRIBUTING.org=
+     for GitHub.
 4. Review the changes in the generated .org and .md files.
 5. Commit *only the .org files*, push branch and create PR.
   - The =.org= → =.md= conversion is done by =ox-hugo= on Netlify.
@ -24,12 +27,14 @@ for your future contributions to Emacs too!
 *documentation* to =doc/ox-hugo-manual.org=.
 3. Run =make md doc=.
 4. Review the changes in the generated .org and .md files.
+   - Ignore the changes shown in =git diff= related to *only* the
+     randomly generated Org ID's (like =org17de7a9=).
 5. Commit (*don't push your branch yet!*).
   - As mentioned above, commit *only the .org files* for documentation.
 6. Run test: =make test= (you *need* to =git commit= i.e. do the above
   step before this step).
-7. Fix commit if test fails.. repeat till test passes.
-8. Push branch and create PR.
+7. Fix your commit(s) if the test fails.. repeat till you succeed.
+8. Push your feature branch and create PR.
 * Debug
 If the =ox-hugo= exports do not work as expected, or if you get an
 error backtrace,
--- a/64
+++ b/64
@ -1,4 +1,4 @@
-# Time-stamp: <2017-11-08 17:16:03 kmodi>
+# Time-stamp: <2017-11-09 11:19:26 kmodi>

 # Makefile to export org documents to md for Hugo from the command line
 # Run just "make" to see usage examples.
@ -9,9 +9,29 @@ ifeq ("$(EMACS_exists)","")
 	EMACS := /tmp/emacs/bin/emacs
 endif

+# EMACS_BIN_SOURCE and EMACS_VERSION are used later in the vcheck rule
+# only if EMACS_exists has evaluated to "".
 EMACS_BIN_SOURCE ?= https://github.com/npostavs/emacs-travis/releases/download/bins
 EMACS_VERSION ?= 25.2

+HUGO ?= hugo
+HUGO_exists := $(shell command -v $(HUGO) 2> /dev/null)
+ifeq ("$(HUGO_exists)","")
+	HUGO := /tmp/hugo/bin/hugo
+endif
+
+# HUGO_BIN_SOURCE and HUGO_VERSION are used later in the vcheck rule
+# only if HUGO_exists has evaluated to "".
+HUGO_BIN_SOURCE ?= https://gitlab.com/kaushalmodi/unofficial-hugo-dev-builds.git
+HUGO_VERSION ?= DEV
+
+# Directory containing the Hugo site's config.toml
+HUGO_BASE_DIR=./
+# Value to be passed to hugo's --baseURL argument
+HUGO_BASE_URL=http://localhost
+# Other hugo arguments
+HUGO_ARGS=
+
 # Set TIMEZONE to the TZ environment variable. If TZ is unset, Emacs
 # uses system wall clock time, which is a platform-dependent default
 # time zone --
@ -40,8 +60,6 @@ ORG_FILE=
 # Function to be run in emacs --batch
 FUNC=

-DOC_SITE_URL=https://ox-hugo.scripter.co/
-
 test_check=1

 subtree_test_files = all-posts.org \
@ -64,11 +82,11 @@ file_test_files = single-posts/post-toml.org \
 # - screenshot-subtree-export-example.org - sets the org-hugo-footer using Local Variables.
 # - writing-hugo-blog-in-org-file-export.org - sets the org-hugo-footer using Local Variables.

-.PHONY: help emacs-batch mdtree mdfile vcheck hugo serve server diff \
+.PHONY: help emacs-batch mdtree mdfile vcheck hugo hugo_doc hugo_test serve server diff \
 	test md testmkgold \
 	test_subtree $(subtree_test_files) \
 	test_file $(file_test_files) \
-	doc_md doc_hugo doc_gh doc \
+	doc_md doc_gh doc \
 	ctemp diffgolden clean

 help:
@ -83,8 +101,9 @@ help:
 	@echo " make serve         <-- Run the hugo server on http://localhost:$(PORT)"
 	@echo " make diff          <-- Run git diff"
 	@echo " make doc_md        <-- Build the Markdown content for the documentation site"
-	@echo " make doc_hugo      <-- Build the documentation site using Hugo"
+	@echo " make hugo_doc      <-- Build the documentation site using Hugo"
 	@echo " make doc_gh        <-- Build README.org and CONTRIBUTING.org for GitHub"
+	@echo " make hugo_test     <-- Build the test site using Hugo"
 	@echo " make clean         <-- Delete the Hugo public/ directory and auto-installed elisp packages"
 	@echo " make               <-- Show this help"

@ -128,21 +147,26 @@ endif
 	(message \"[Version check] %s\" (org-version nil :full))\
 	)" \
 	--kill
-# Thu Sep 21 00:36:23 EDT 2017 - kmodi
-# Don't check hugo version for now, as Travis fails
-#	@hugo version
+ifeq ("$(HUGO_exists)","")
+	@mkdir -p /tmp/hugo
+	@find /tmp/hugo -maxdepth 1 -type d -name bin -exec rm -rf "{}" \;
+	@git clone $(HUGO_BIN_SOURCE) /tmp/hugo/bin
+	@tar xf /tmp/hugo/bin/hugo_DEV-Linux-64bit.tar.xz -C /tmp/hugo/bin
+endif
+	@$(HUGO) version

 hugo: vcheck
-	@hugo
+	@cd $(HUGO_BASE_DIR) && $(HUGO) --baseURL=$(HUGO_BASE_URL) $(HUGO_ARGS)
+
+hugo_doc:
+	@$(MAKE) hugo HUGO_BASE_DIR=./doc HUGO_BASE_URL=https://ox-hugo.scripter.co/
+
+hugo_test:
+	@$(MAKE) hugo HUGO=/tmp/hugo/bin/hugo HUGO_BASE_DIR=./test/site HUGO_BASE_URL=https://ox-hugo.scripter.co/test HUGO_ARGS=--buildDrafts

 serve server: vcheck
-	@echo "Serving the site on http://localhost:$(PORT) .."
-	@hugo server \
-	--buildDrafts \
-	--buildFuture \
-	--navigateToChanged \
-	--baseURL http://localhost \
-	--port $(PORT)
+	@echo "Serving the site on $(HUGO_BASE_URL):$(PORT) .."
+	@cd $(HUGO_BASE_DIR) && $(HUGO) server --baseURL=$(HUGO_BASE_URL) --port $(PORT) --buildDrafts --buildFuture --navigateToChanged

 diff:
 	@git diff
@ -186,15 +210,12 @@ doc_md:
 	@$(MAKE) mdtree ORG_FILE=ox-hugo-manual.org ORG_FILE_DIR=./doc
 	@echo "[Doc Site] Done"

-doc_hugo:
-	@cd ./doc && hugo --baseURL=$(DOC_SITE_URL)
-
 doc_gh:
 	@echo "[GitHub Docs] Generating README.org and CONTRIBUTING.org for GitHub .."
 	@$(MAKE) emacs-batch FUNC=ox-hugo-export-gh-doc ORG_FILE=github-files.org ORG_FILE_DIR=./doc
 	@echo "[GitHub Docs] Done"

-doc: doc_md doc_hugo doc_gh
+doc: doc_md hugo_doc doc_gh

 ctemp:
 	@find $(OX_HUGO_TEST_SITE_DIR)/content -name "*.*~" -delete
@ -219,6 +240,7 @@ clean: ctemp
 	@rm -rf $(OX_HUGO_TEST_SITE_DIR)/public $(OX_HUGO_TEST_SITE_DIR)/content-golden
 	@rm -rf $(OX_HUGO_ELPA)
 	@rm -rf ./doc/public
+	@rm -rf /tmp/hugo/bin

 # Set a make variable during rule execution
 # https://stackoverflow.com/a/1909390/1219634
--- a/doc/ox-hugo-manual.org
+++ b/doc/ox-hugo-manual.org
@ -336,6 +336,9 @@ for your future contributions to Emacs too!
 1. Clone this repo.
 2. Add/edit documentation to =doc/ox-hugo-manual.org=.
 3. Run =make doc=.
+   - This generates the Markdown files for the =ox-hugo= documentation
+     site and the .org files like =README.org= and =CONTRIBUTING.org=
+     for GitHub.
 4. Review the changes in the generated .org and .md files.
 5. Commit *only the .org files*, push branch and create PR.
   - The =.org= → =.md= conversion is done by =ox-hugo= on Netlify.
@ -345,12 +348,14 @@ for your future contributions to Emacs too!
 *documentation* to =doc/ox-hugo-manual.org=.
 3. Run =make md doc=.
 4. Review the changes in the generated .org and .md files.
+   - Ignore the changes shown in =git diff= related to *only* the
+     randomly generated Org ID's (like =org17de7a9=).
 5. Commit (*don't push your branch yet!*).
   - As mentioned above, commit *only the .org files* for documentation.
 6. Run test: =make test= (you *need* to =git commit= i.e. do the above
   step before this step).
-7. Fix commit if test fails.. repeat till test passes.
-8. Push branch and create PR.
+7. Fix your commit(s) if the test fails.. repeat till you succeed.
+8. Push your feature branch and create PR.
 ** Debug
 :PROPERTIES:
 :CUSTOM_ID: debug
@ -534,7 +539,7 @@ to set that up for either of the above two blogging flows.
 - [X] Travis CI Integration -- Checks with emacs versions starting from
  24.4->25.2, with the latest stable version of =org-plus-contrib=.
 - [X] [[https://ox-hugo.scripter.co][Documentation site]] -- Generated using =ox-hugo= itself (=make
-  doc_md doc_hugo=).
+  doc_md hugo_doc=).
 - [X] GitHub repo files: [[https://github.com/kaushalmodi/ox-hugo/blob/master/README.org][~README.org~]] and [[https://github.com/kaushalmodi/ox-hugo/blob/master/CONTRIBUTING.org][~CONTRIBUTING.org~]] --
  Generated using =ox-org= (=make doc_gh=).
 - [X] [[../test][Test site]] -- Regenerated after each commit to this repo (=make
@ -584,21 +589,20 @@ Check out the [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/tes
 Org->Hugo content and meta-data translation features. [[https://github.com/kaushalmodi/ox-hugo/tree/master/test/site/content/posts][Here]] are the
 exported Markdown files.
 **** How to try =ox-hugo= on that site?
-1. Clone this repo.
-2. =cd= to the =test/site/= directory and do:
+1. Clone this repo and do:
   #+BEGIN_EXAMPLE
-   make serve
+   make serve HUGO_BASE_DIR=test/site
   #+END_EXAMPLE
-   - *Requires Hugo 0.25+*
-3. Open =http://localhost:1337= in your browser.
-4. In a different terminal, =cd= to the same =test/site/= directory.
-5. Run:
+   - *Requires Hugo 0.25+ for =--navigateToChanged= switch.*
+2. Open =http://localhost:1337= in your browser.
+3. In a different terminal, =cd= to the repo directory.
+4. Run:
   #+BEGIN_EXAMPLE
-   make mdtree ORG=content-org/all-posts.org
+   make md
   #+END_EXAMPLE
-6. In few seconds, dozens of test posts will get created, with the
- =hugo server= aided preview in the browser zapping through each new
-   created post.
+5. In few seconds, over a hundred test posts will get created, with
+   the =hugo server= aided preview in the browser zapping through each
+   new created post.
 **** Alternative way
 1. Clone this repo.
 2. =cd= to the =test/site/= directory and do:
@ -613,9 +617,9 @@ exported Markdown files.
 5. Open the {{{ox-hugo-test-file}}} file.
 6. =C-c C-e H A= -- That will export *all* subtrees in the file to
   Markdown files.
-7. In few seconds, dozens of test posts will get created, with the
- =hugo server= aided preview in the browser zapping through each new
-   created post (needs that new feature =--navigateToChanged=
+7. In few seconds, over a hundred test posts will get created, with
+   the =hugo server= aided preview in the browser zapping through each
+   new created post (because of that new feature =--navigateToChanged=
   introduced in Hugo 0.25).
 ** Enhancements
 :PROPERTIES: