forked from github/pelican
Add dual dev/publish modes to quickstart script
Certain configuration options are more useful in production than they are in development. Some examples might be absolute URLs, external analytics service identifiers, Disqus comments, etc. This version of the quickstart script creates two configuration files: one for development and the other for use when publishing. In addition, the related docs have been expanded considerably. Last but not least, the quickstart script will now detect whether there is a project folder associated with the currently active virtualenv (if any) and use it by default.
This commit is contained in:
Justin Mayer
parent
d8b85580dc
commit
764a2cfa51
7 changed files with 195 additions and 89 deletions
|
|
@ -1,15 +1,70 @@
|
|||
Getting started
|
||||
###############
|
||||
|
||||
Installing
|
||||
==========
|
||||
Kickstart a blog
|
||||
================
|
||||
|
||||
You're ready? Let's go! You can install Pelican via several different methods.
|
||||
You're ready? Let's go! Following is a brief tutorial for those who want to get
|
||||
started right away. Subsequent sections below will cover individual topics in
|
||||
greater detail. To get started, here are some recommended install steps for
|
||||
Pelican::
|
||||
|
||||
$ sudo pip install --upgrade virtualenv virtualenvwrapper
|
||||
$ mkvirtualenv pelican
|
||||
$ pip install pelican Markdown
|
||||
$ mkdir ~/code/yoursitename # (where you want your new site code to be saved)
|
||||
$ cd ~/code/yoursitename
|
||||
$ setvirtualenvproject
|
||||
$ pelican-quickstart
|
||||
|
||||
Once you've run that last ``pelican-quickstart`` command, you'll be asked some
|
||||
questions about your site. 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 preview the site in your browser, open a new terminal tab and enter::
|
||||
|
||||
$ workon yoursitename
|
||||
$ 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.
|
||||
|
||||
Closing the current terminal session will also close the virtual environment in
|
||||
which we installed Pelican. In the future, when you want to work on your site,
|
||||
you can activate its virtual environment via::
|
||||
|
||||
$ workon yoursitename
|
||||
|
||||
Not only will that command activate your new site's virtual environment, but it
|
||||
will also automatically change your working directory to your site project.
|
||||
|
||||
Installing Pelican
|
||||
==================
|
||||
|
||||
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 +73,12 @@ 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
|
||||
|
||||
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
|
||||
have the project source, you can install Pelican using the distutils
|
||||
be installed via ``pip`` or ``easy_install`` as noted above. Alternatively, if
|
||||
you have the project source, you can install Pelican using the distutils
|
||||
method::
|
||||
|
||||
$ cd path-to-Pelican-source
|
||||
|
|
@ -34,6 +89,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
|
||||
---------
|
||||
|
||||
|
|
@ -83,7 +143,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 +164,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/``
|
||||
folder.
|
||||
The above command will generate your weblog and save it in the ``content/``
|
||||
folder, using the default theme to produce a simple site. It's not
|
||||
very sexy, as it's just simple HTML output (without any style). You can create
|
||||
your own style if you want.
|
||||
|
||||
The above command will use the default theme to produce a simple site. It's not
|
||||
very sexy, as it's just simple HTML output (without any style).
|
||||
|
||||
You can create your own style if you want. Have a look at the help to see all
|
||||
the options you can use::
|
||||
Pelican has other command-line switches available. 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
|
||||
seconds by just answering a few questions. Just run ``pelican-quickstart`` and
|
||||
you're done! (Added in Pelican 3.0)
|
||||
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.
|
||||
|
||||
Pages
|
||||
-----
|
||||
|
|
@ -209,13 +269,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
|
||||
-----------------
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
not.
|
||||
`RELATIVE_URLS` (``True``) Defines whether Pelican should use document-relative URLs or
|
||||
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
|
||||
root-relative URL structure. If `SITEURL` is specified
|
||||
explicitly, there should be no trailing slash at the end,
|
||||
and URLs will be generated with an absolute URL structure
|
||||
(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.
|
||||
so it is best to specify your SITEURL; if you do not, feeds
|
||||
will not be generated with properly-formed URLs. You should
|
||||
include ``http://`` and your domain, with no trailing
|
||||
slash at the end. Example: ``SITEURL = 'http://mydomain.com'``
|
||||
`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
|
||||
|
|
|
|||
|
|
@ -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):
|
||||
CONF['ftp_host'] = ask('What is the hostname of your FTP server ?', str, CONF['ftp_host'])
|
||||
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_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):
|
||||
CONF['ssh_host'] = ask('What is the hostname of your SSH server ?', str, CONF['ssh_host'])
|
||||
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_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):
|
||||
CONF['dropbox_dir'] = ask('Where is your Dropbox directory ?', str, CONF['dropbox_dir'])
|
||||
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'])
|
||||
|
||||
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:
|
||||
for line in get_template('pelican.conf.py'):
|
||||
with open(os.path.join(CONF['basedir'], 'pelicanconf.py'), 'w') as fd:
|
||||
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()
|
||||
|
|
|
|||
|
|
@ -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 ' ssh_upload upload the web site using SSH '
|
||||
@echo ' dropbox_upload upload the web site using Dropbox '
|
||||
@echo ' rsync_upload upload the web site using rsync/ssh'
|
||||
@echo ' make publish generate using production settings '
|
||||
@echo ' ftp_upload upload the web site via FTP '
|
||||
@echo ' ssh_upload upload the web site via 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)
|
||||
mkdir $$(OUTPUTDIR)
|
||||
find $$(OUTPUTDIR) -mindepth 1 -delete
|
||||
|
||||
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
|
||||
|
|
|
|||
17
pelican/tools/templates/publishconf.py.in
Normal file
17
pelican/tools/templates/publishconf.py.in
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
#!/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 = ""
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue