From 30192b2318b71cac718f8e116edc288611701085 Mon Sep 17 00:00:00 2001 From: Justin Mayer Date: Mon, 29 Jul 2013 11:03:14 -0700 Subject: [PATCH] Add fabfile generation to pelican-quickstart This commit adds optional fabfile.py generation during the pelican-quickstart process. Reasons include: * "make" is cumbersome to install on Windows * Fabric runs in any Python environment * fabfile is just Python and thus more flexible and extensible This is an initial implementation and does not currently provide as many upload options as its Makefile counterpart. Refs #584. --- docs/getting_started.rst | 83 ++++++++++++++++++++++++--- pelican/tools/pelican_quickstart.py | 14 ++++- pelican/tools/templates/fabfile.py.in | 47 +++++++++++++++ 3 files changed, 133 insertions(+), 11 deletions(-) create mode 100644 pelican/tools/templates/fabfile.py.in diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 383acdc4..b8ffbf43 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -152,21 +152,87 @@ if you plan to create non-chronological content):: │   └── (pages) ├── output ├── develop_server.sh + ├── fabfile.py ├── Makefile ├── pelicanconf.py # Main settings file └── publishconf.py # Settings to use when ready to publish The next step is to begin to 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.) +been created for you. (See the **Writing content using Pelican** section below +for more information about how to format your content.) Once you have written some content to generate, you can use the ``pelican`` command to generate your site, which will be placed in the output folder. -Alternatively, you can use automation tools that "wrap" the ``pelican`` command -to simplify the process of generating, previewing, and uploading your site. One -such tool is the ``Makefile`` that's automatically created for you when you use -``pelican-quickstart`` to create a skeleton project. To use ``make`` to -generate your site, run:: + +Automation tools +================ + +While the ``pelican`` command is the canonical way to generate your site, +automation tools can be used to streamline the generation and publication +flow. One of the questions asked during the ``pelican-quickstart`` process +described above pertains to whether you want to automate site generation and +publication. If you answered "yes" to that question, a ``fabfile.py`` and +``Makefile`` will be generated in the root of your project. These files, +pre-populated with certain information gleaned from other answers provided +during the ``pelican-quickstart`` process, are meant as a starting point and +should be customized to fit your particular needs and usage patterns. If you +find one or both of these automation tools to be of limited utility, these +files can deleted at any time and will not affect usage of the canonical +``pelican`` command. + +Following are automation tools that "wrap" the ``pelican`` command and can +simplify the process of generating, previewing, and uploading your site. + +Fabric +------ + +The advantage of Fabric_ is that it is written in Python and thus can be used +in a wide range of environments. The downside is that it must be installed +separately. Use the following command to install Fabric, prefixing with +``sudo`` if your environment requires it:: + + $ pip install Fabric + +Take a moment to open the ``fabfile.py`` file that was generated in your +project root. You will see a number of commands, any one of which can be +renamed, removed, and/or customized to your liking. Using the out-of-the-box +configuration, you can generate your site via:: + + $ fab build + +If you'd prefer to have Pelican automatically regenerate your site every time a +change is detected (which is handy when testing locally), use the following +command instead:: + + $ fab regenerate + +To serve the generated site so it can be previewed in your browser at +http://localhost:8000/:: + + $ fab serve + +If during the ``pelican-quickstart`` process you answered "yes" when asked +whether you want to upload your site via SSH, you can use the following command +to publish your site via rsync over SSH:: + + $ fab publish + +These are just a few of the commands available by default, so feel free to +explore ``fabfile.py`` and see what other commands are available. More +importantly, don't hesitate to customize ``fabfile.py`` to suit your specific +needs and preferences. + +Make +---- + +A ``Makefile`` is also automatically created for you when you say "yes" to +the relevant question during the ``pelican-quickstart`` process. The advantage +of this method is that the ``make`` command is built into most POSIX systems +and thus doesn't require installing anything else in order to use it. The +downside is that non-POSIX systems (e.g., Windows) do not include ``make``, +and installing it on those systems can be a non-trivial task. + +If you want to use ``make`` to generate your site, run:: $ make html @@ -177,7 +243,7 @@ command instead:: $ make regenerate To serve the generated site so it can be previewed in your browser at -http://localhost:8000:: +http://localhost:8000/:: $ make serve @@ -484,3 +550,4 @@ listed on the index page nor on any category page. .. _virtualenv: http://www.virtualenv.org/ .. _W3C ISO 8601: http://www.w3.org/TR/NOTE-datetime +.. _Fabric: http://fabfile.org/ diff --git a/pelican/tools/pelican_quickstart.py b/pelican/tools/pelican_quickstart.py index e62bc5ca..46ba1a82 100755 --- a/pelican/tools/pelican_quickstart.py +++ b/pelican/tools/pelican_quickstart.py @@ -193,10 +193,10 @@ needed by Pelican. else: CONF['default_pagination'] = False - mkfile = ask('Do you want to generate a Makefile to easily manage your website?', bool, True) + automation = ask('Do you want to generate a Fabfile/Makefile to automate generation and publishing?', bool, True) develop = ask('Do you want an auto-reload & simpleHTTP script to assist with theme and site development?', bool, True) - if mkfile: + if automation: 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_compat, CONF['ftp_host']) CONF['ftp_user'] = ask('What is your username on that server?', str_compat, CONF['ftp_user']) @@ -243,7 +243,15 @@ needed by Pelican. except OSError as e: print('Error: {0}'.format(e)) - if mkfile: + if automation: + try: + with codecs.open(os.path.join(CONF['basedir'], 'fabfile.py'), 'w', 'utf-8') as fd: + for line in get_template('fabfile.py'): + template = string.Template(line) + fd.write(template.safe_substitute(CONF)) + fd.close() + except OSError as e: + print('Error: {0}'.format(e)) try: with codecs.open(os.path.join(CONF['basedir'], 'Makefile'), 'w', 'utf-8') as fd: mkfile_template_name = 'Makefile' diff --git a/pelican/tools/templates/fabfile.py.in b/pelican/tools/templates/fabfile.py.in new file mode 100644 index 00000000..e991b763 --- /dev/null +++ b/pelican/tools/templates/fabfile.py.in @@ -0,0 +1,47 @@ +from fabric.api import * +import fabric.contrib.project as project +import os + +# Local path configuration (can be absolute or relative to fabfile) +env.deploy_path = 'output' + +# Remote server configuration +production = '$ssh_user@$ssh_host:$ssh_port' +dest_path = '$ssh_target_dir' + +DEPLOY_PATH = env.deploy_path + +def clean(): + if os.path.isdir(DEPLOY_PATH): + local('rm -rf {deploy_path}'.format(**env)) + local('mkdir {deploy_path}'.format(**env)) + +def build(): + local('pelican -s pelicanconf.py') + +def rebuild(): + clean() + build() + +def regenerate(): + local('pelican -r -s pelicanconf.py') + +def serve(): + local('cd {deploy_path} && python -m SimpleHTTPServer'.format(**env)) + +def reserve(): + build() + serve() + +def preview(): + local('pelican -s publishconf.py') + +@hosts(production) +def publish(): + local('pelican -s publishconf.py') + project.rsync_project( + remote_dir=dest_path, + exclude=".DS_Store", + local_dir=DEPLOY_PATH.rstrip('/') + '/', + delete=True + )