Merge pull request #403 from justinmayer/quickstart

Add dual dev/publish modes to quickstart script

docs/getting_started.rst

@@ -1,15 +1,15 @@
 Getting started
 ###############
 
-Installing
+Installing Pelican
-==========
+==================
 
 You're ready? Let's go! You can install Pelican via several different methods.
 The simplest is via `pip <http://www.pip-installer.org/>`_::
 
     $ pip install pelican
 
-If you don't have pip installed, an alternative method is easy_install::
+If you don't have ``pip`` installed, an alternative method is ``easy_install``::
 
     $ easy_install pelican
 
@@ -18,12 +18,13 @@ a virtual environment for Pelican via `virtualenv <http://www.virtualenv.org/>`_
 and `virtualenvwrapper <http://www.doughellmann.com/projects/virtualenvwrapper/>`_
 before installing Pelican::
 
-    $ pip install virtualenvwrapper
+    $ sudo pip install --upgrade virtualenv virtualenvwrapper
     $ mkvirtualenv pelican
+    $ pip install pelican
 
 Once the virtual environment has been created and activated, Pelican can be
-be installed via pip or easy_install as noted above. Alternatively, if you
+be installed via ``pip`` or ``easy_install`` as noted above. Alternatively, if
-have the project source, you can install Pelican using the distutils 
+you have the project source, you can install Pelican using the distutils 
 method::
 
     $ cd path-to-Pelican-source
@@ -34,6 +35,11 @@ version of Pelican rather than a stable release, use the following command::
 
     $ pip install -e git://github.com/ametaireau/pelican#egg=pelican
 
+If you plan on using Markdown as a markup format, you'll need to install the
+Markdown library as well::
+
+    $ pip install Markdown
+
 Upgrading
 ---------
 
@@ -62,6 +68,59 @@ Optionally:
 * pygments, for syntax highlighting
 * Markdown, for supporting Markdown as an input format
 
+Kickstart a blog
+================
+
+Following is a brief tutorial for those who want to get started right away.
+We're going to assume Pelican was installed in a virtual environment via the
+following steps (if you're not using a virtual environment for Pelican, you can
+skip to the ``pelican-quickstart`` command)::
+
+    $ sudo pip install --upgrade virtualenv virtualenvwrapper
+    $ mkvirtualenv pelican
+    $ pip install pelican Markdown
+
+Next we'll create a directory to house our site content and configuration files,
+which can be located any place you prefer, and associate this new project with
+the currently-active virtual environment::
+
+    $ mkdir ~/code/yoursitename
+    $ cd ~/code/yoursitename
+    $ setvirtualenvproject
+
+Now we can run the ``pelican-quickstart`` command, which will ask some questions
+about your site::
+
+    $ pelican-quickstart
+
+Once you finish answering all the questions, you can begin adding content to the
+*content* folder that has been created for you. (See *Writing articles using
+Pelican* section below for more information about how to format your content.)
+Once you have some content to generate, you can convert it to HTML via the
+following command::
+
+    $ make html
+
+If you'd prefer to have Pelican automatically regenerate your site every time a
+change is detected (handy when testing locally), use the following command
+instead::
+
+    $ make regenerate
+
+To serve the site so it can be previewed in your browser::
+
+    $ make serve
+
+Visit http://localhost:8000 in your browser to see your site.
+
+When you're ready to publish your site, you can upload it via the method(s) you
+chose during the ``pelican-quickstart`` questionnaire. For this example, we'll
+use rsync over ssh::
+
+    $ make rsync_upload
+
+That's it! Your site should now be live.
+
 Writing articles using Pelican
 ==============================
 
@@ -83,7 +142,6 @@ following syntax (give your file the ``.rst`` extension)::
     :category: yeah
     :author: Alexis Metaireau
 
-
 You can also use Markdown syntax (with a file ending in ``.md``).
 Markdown generation will not work until you explicitly install the ``Markdown``
 package, which can be done via ``pip install Markdown``. Metadata syntax for
@@ -105,27 +163,28 @@ example, a file located at ``python/foobar/myfoobar.rst`` will have a category o
 Generate your blog
 ------------------
 
-To launch Pelican, just use the ``pelican`` command::
+The ``make`` shortcut commands mentioned in the ``Kickstart a blog`` section
+are mostly wrappers around the ``pelican`` command that generates the HTML from
+the content. The ``pelican`` command can also be run directly::
 
     $ pelican /path/to/your/content/ [-s path/to/your/settings.py]
 
-And… that's all! Your weblog will be generated and saved in the ``content/``
+The above command will generate your weblog and save it in the ``content/``
-folder.
+folder, using the default theme to produce a simple site. The default theme is
+simple HTML without styling and is provided so folks may use it as a basis for
+creating their own themes.
 
-The above command will use the default theme to produce a simple site. It's not
+Pelican has other command-line switches available. Have a look at the help to
-very sexy, as it's just simple HTML output (without any style).
+see all the options you can use::
-
-You can create your own style if you want. Have a look at the help to see all
-the options you can use::
 
     $ pelican --help
 
-Kickstart a blog
+Auto-reload
-----------------
+-----------
 
-You also can use the ``pelican-quickstart`` script to start a new blog in
+It's possible to tell Pelican to watch for your modifications, instead of
-seconds by just answering a few questions. Just run ``pelican-quickstart`` and
+manually re-running it every time you want to see your changes. To enable this,
-you're done! (Added in Pelican 3.0)
+run the ``pelican`` command with the ``-r`` or ``--autoreload`` option.
 
 Pages
 -----
@@ -209,13 +268,6 @@ For Markdown, format your code blocks thusly::
 The specified identifier should be one that appears on the 
 `list of available lexers <http://pygments.org/docs/lexers/>`_.
 
-Auto-reload
------------
-
-It's possible to tell Pelican to watch for your modifications, instead of
-manually re-running it every time you want to see your changes. To enable this,
-run the ``pelican`` command with the ``-r`` or ``--autoreload`` option.
-
 Publishing drafts
 -----------------
 

docs/settings.rst

@@ -59,18 +59,16 @@ Setting name (default value)                                            What doe
 `PDF_GENERATOR` (``False``)                                             Set to True if you want to have PDF versions
                                                                         of your documents. You will need to install
                                                                         `rst2pdf`.
-`RELATIVE_URLS` (``True``)                                              Defines whether Pelican should use relative URLs or
+`RELATIVE_URLS` (``True``)                                              Defines whether Pelican should use document-relative URLs or
-                                                                        not.
+                                                                        not. If set to ``False``, Pelican will use the SITEURL
+                                                                        setting to construct absolute URLs.
 `PLUGINS` (``[]``)                                                      The list of plugins to load. See :ref:`plugins`.
 `SITENAME` (``'A Pelican Blog'``)                                       Your site name
 `SITEURL`                                                               Base URL of your website. Not defined by default,
-                                                                        which means the base URL is assumed to be "/" with a
+                                                                        so it is best to specify your SITEURL; if you do not, feeds
-                                                                        root-relative URL structure. If `SITEURL` is specified
+                                                                        will not be generated with properly-formed URLs. You should 
-                                                                        explicitly, there should be no trailing slash at the end,
+                                                                        include ``http://`` and your domain, with no trailing
-                                                                        and URLs will be generated with an absolute URL structure
+                                                                        slash at the end. Example: ``SITEURL = 'http://mydomain.com'``
-                                                                        (including the domain). If you want to use relative URLs
-                                                                        instead of root-relative or absolute URLs, you should
-                                                                        instead use the `RELATIVE_URL` setting.
 `STATIC_PATHS` (``['images']``)                                         The static paths you want to have accessible
                                                                         on the output path "static". By default,
                                                                         Pelican will copy the 'images' folder to the
@@ -107,6 +105,15 @@ Setting name (default value)                                            What doe
 URL settings
 ------------
 
+The first thing to understand is that there are currently two supported methods
+for URL formation: *relative* and *absolute*. Document-relative URLs are useful
+when testing locally, and absolute URLs are reliable and most useful when
+publishing. One method of supporting both is to have one Pelican configuration
+file for local development and another for publishing. To see an example of this
+type of setup, use the ``pelican-quickstart`` script as described at the top of
+the :doc:`Getting Started<getting_started>` page, which will produce two separate
+configuration files for local development and publishing, respectively.
+
 You can customize the URLs and locations where files will be saved. The URLs and
 SAVE_AS variables use Python's format strings. These variables allow you to place
 your articles in a location such as '{slug}/index.html' and link to them as

pelican/tools/pelican_quickstart.py

@@ -24,6 +24,7 @@ CONF = {
     'ssh_target_dir': '/var/www',
     'dropbox_dir' : '~/Dropbox/Public/',
     'default_pagination' : 10,
+    'siteurl': '',
     'lang': 'en'
 }
 
@@ -138,35 +139,44 @@ Please answer the following questions so this script can generate the files need
 
     '''.format(v=__version__))
 
-    CONF['basedir'] = os.path.abspath(ask('Where do you want to create your new web site?', answer=str, default=args.path))
+    project = os.path.join(os.environ['VIRTUAL_ENV'], '.project')
+    if os.path.isfile(project):
+        CONF['basedir'] = open(project, 'r').read().rstrip("\n")
+        print('Using project associated with current virtual environment. Will save to:\n%s\n' % CONF['basedir'])
+    else:
+        CONF['basedir'] = os.path.abspath(ask('Where do you want to create your new web site?', answer=str, default=args.path))
+
     CONF['sitename'] = ask('What will be the title of this web site?', answer=str, default=args.title)
     CONF['author'] = ask('Who will be the author of this web site?', answer=str, default=args.author)
-    CONF['lang'] = ask('What will be the default language of this web site ?', str, args.lang or CONF['lang'], 2)
+    CONF['lang'] = ask('What will be the default language of this web site?', str, args.lang or CONF['lang'], 2)
 
-    CONF['with_pagination'] = ask('Do you want to enable article pagination ?', bool, bool(CONF['default_pagination']))
+    if ask('Do you want to specify a URL prefix? e.g., http://example.com  ', answer=bool, default=True):
+        CONF['siteurl'] = ask('What is your URL prefix? (see above example; no trailing slash)', str, CONF['siteurl'])
+
+    CONF['with_pagination'] = ask('Do you want to enable article pagination?', bool, bool(CONF['default_pagination']))
 
     if CONF['with_pagination']:
         CONF['default_pagination'] = ask('How many articles per page do you want?', int, CONF['default_pagination'])
     else:
         CONF['default_pagination'] = False
 
-    mkfile = ask('Do you want to generate a Makefile to easily manage your website ?', bool, True)
+    mkfile = ask('Do you want to generate a Makefile to easily manage your website?', bool, True)
 
     if mkfile:
-        if ask('Do you want to upload your website using FTP ?', answer=bool, default=False):
+        if ask('Do you want to upload your website using FTP?', answer=bool, default=False):
-            CONF['ftp_host'] = ask('What is the hostname of your FTP server ?', str, CONF['ftp_host'])
+            CONF['ftp_host'] = ask('What is the hostname of your FTP server?', str, CONF['ftp_host'])
             CONF['ftp_user'] = ask('What is your username on that server?', str, CONF['ftp_user'])
             CONF['ftp_target_dir'] = ask('Where do you want to put your web site on that server?', str, CONF['ftp_target_dir']) 
-        if ask('Do you want to upload your website using SSH ?', answer=bool, default=False):
+        if ask('Do you want to upload your website using SSH?', answer=bool, default=False):
-            CONF['ssh_host'] = ask('What is the hostname of your SSH server ?', str, CONF['ssh_host'])
+            CONF['ssh_host'] = ask('What is the hostname of your SSH server?', str, CONF['ssh_host'])
             CONF['ssh_port'] = ask('What is the port of your SSH server?', int, CONF['ssh_port'])
             CONF['ssh_user'] = ask('What is your username on that server?', str, CONF['ssh_user'])
             CONF['ssh_target_dir'] = ask('Where do you want to put your web site on that server?', str, CONF['ssh_target_dir'])
-        if ask('Do you want to upload your website using Dropbox ?', answer=bool, default=False):
+        if ask('Do you want to upload your website using Dropbox?', answer=bool, default=False):
-            CONF['dropbox_dir'] = ask('Where is your Dropbox directory ?', str, CONF['dropbox_dir'])
+            CONF['dropbox_dir'] = ask('Where is your Dropbox directory?', str, CONF['dropbox_dir'])
 
     try:
-        os.makedirs(os.path.join(CONF['basedir'], 'src'))
+        os.makedirs(os.path.join(CONF['basedir'], 'content'))
     except OSError, e:
         print('Error: {0}'.format(e))
 
@@ -176,8 +186,17 @@ Please answer the following questions so this script can generate the files need
         print('Error: {0}'.format(e))
 
     try:
-        with open(os.path.join(CONF['basedir'], 'pelican.conf.py'), 'w') as fd:
+        with open(os.path.join(CONF['basedir'], 'pelicanconf.py'), 'w') as fd:
-            for line in get_template('pelican.conf.py'):
+            for line in get_template('pelicanconf.py'):
+                template = string.Template(line)
+                fd.write(template.safe_substitute(CONF))
+            fd.close()
+    except OSError, e:
+        print('Error: {0}'.format(e))
+
+    try:
+        with open(os.path.join(CONF['basedir'], 'publishconf.py'), 'w') as fd:
+            for line in get_template('publishconf.py'):
                 template = string.Template(line)
                 fd.write(template.safe_substitute(CONF))
             fd.close()

pelican/tools/templates/Makefile.in

@@ -2,9 +2,10 @@ PELICAN=$pelican
 PELICANOPTS=$pelicanopts
 
 BASEDIR=$$(PWD)
-INPUTDIR=$$(BASEDIR)/src
+INPUTDIR=$$(BASEDIR)/content
 OUTPUTDIR=$$(BASEDIR)/output
-CONFFILE=$$(BASEDIR)/pelican.conf.py
+CONFFILE=$$(BASEDIR)/pelicanconf.py
+PUBLISHCONF=$$(BASEDIR)/publishconf.py
 
 FTP_HOST=$ftp_host
 FTP_USER=$ftp_user
@@ -23,10 +24,11 @@ help:
 	@echo 'Usage:                                                                 '
 	@echo '   make html                        (re)generate the web site          '
 	@echo '   make clean                       remove the generated files         '
-	@echo '   ftp_upload                       upload the web site using FTP      '
+	@echo '   make publish                     generate using production settings '
-	@echo '   ssh_upload                       upload the web site using SSH      '
+	@echo '   ftp_upload                       upload the web site via FTP        '
-	@echo '   dropbox_upload                   upload the web site using Dropbox  '
+	@echo '   ssh_upload                       upload the web site via SSH        '
-	@echo '   rsync_upload                     upload the web site using rsync/ssh'
+	@echo '   dropbox_upload                   upload the web site via Dropbox    '
+	@echo '   rsync_upload                     upload the web site via rsync/ssh  '
 	@echo '                                                                       '
 
 
@@ -37,23 +39,31 @@ $$(OUTPUTDIR)/%.html:
 	$$(PELICAN) $$(INPUTDIR) -o $$(OUTPUTDIR) -s $$(CONFFILE) $$(PELICANOPTS)
 
 clean:
-	rm -fr $$(OUTPUTDIR)
+	find $$(OUTPUTDIR) -mindepth 1 -delete
-	mkdir $$(OUTPUTDIR)
 
-dropbox_upload: $$(OUTPUTDIR)/index.html
+regenerate: clean
+	$$(PELICAN) -r $$(INPUTDIR) -o $$(OUTPUTDIR) -s $$(CONFFILE) $$(PELICANOPTS)
+
+serve:
+	cd $$(OUTPUTDIR) && python -m SimpleHTTPServer
+
+publish:
+	$$(PELICAN) $$(INPUTDIR) -o $$(OUTPUTDIR) -s $$(PUBLISHCONF) $$(PELICANOPTS)
+
+dropbox_upload: publish
 	cp -r $$(OUTPUTDIR)/* $$(DROPBOX_DIR)
 
-ssh_upload: $$(OUTPUTDIR)/index.html
+ssh_upload: publish
 	scp -P $$(SSH_PORT) -r $$(OUTPUTDIR)/* $$(SSH_USER)@$$(SSH_HOST):$$(SSH_TARGET_DIR)
 
-rsync_upload: $$(OUTPUTDIR)/index.html
+rsync_upload: publish
 	rsync -e "ssh -p $(SSH_PORT)" -P -rvz --delete $(OUTPUTDIR)/* $(SSH_USER)@$(SSH_HOST):$(SSH_TARGET_DIR)
 
-ftp_upload: $$(OUTPUTDIR)/index.html
+ftp_upload: publish
 	lftp ftp://$$(FTP_USER)@$$(FTP_HOST) -e "mirror -R $$(OUTPUTDIR) $$(FTP_TARGET_DIR) ; quit"
 
-github: $$(OUTPUTDIR)/index.html
+github: publish
 	ghp-import $$(OUTPUTDIR)
 	git push origin gh-pages
 
-.PHONY: html help clean ftp_upload ssh_upload rsync_upload dropbox_upload github
+.PHONY: html help clean regenerate serve publish ftp_upload ssh_upload rsync_upload dropbox_upload github

pelican/tools/templates/publishconf.py.in

@@ -0,0 +1,16 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*- #
+
+from pelicanconf import *
+
+SITEURL = '$siteurl'
+
+DELETE_OUTPUT_DIRECTORY = True
+
+# Following items are often useful when publishing
+
+# Uncomment following line for absolute URLs in production:
+#RELATIVE_URLS = False
+
+#DISQUS_SITENAME = ""
+#GOOGLE_ANALYTICS = ""