179 lines
6 KiB
ReStructuredText
179 lines
6 KiB
ReStructuredText
|
.. _commands:
|
||
|
|
|
||
|
|
ABlog Commands
|
||
|
|
==============
|
||
|
|
|
||
|
|
.. post:: Mar 1, 2015
|
||
|
|
:tags: config, commands
|
||
|
|
:author: Ahmet, Mehmet
|
||
|
|
:category: Manual
|
||
|
|
:location: SF
|
||
|
|
|
||
|
|
|
||
|
|
``ablog`` commands are for streamlining blog operations, i.e. building, serving, and viewing blog pages, as well as starting a new blog::
|
||
|
|
|
||
|
|
$ ablog
|
||
|
|
usage: ablog [-h] [-v] {start,build,clean,serve,post,deploy} ...
|
||
|
|
|
||
|
|
ABlog for blogging with Sphinx
|
||
|
|
|
||
|
|
optional arguments:
|
||
|
|
-h, --help show this help message and exit
|
||
|
|
-v, --version print ABlog version and exit
|
||
|
|
|
||
|
|
subcommands:
|
||
|
|
{start,build,clean,serve,post,deploy}
|
||
|
|
start start a new blog project
|
||
|
|
build build your blog project
|
||
|
|
clean clean your blog build files
|
||
|
|
serve serve and view your project
|
||
|
|
post create a blank post
|
||
|
|
deploy deploy your website build files
|
||
|
|
|
||
|
|
See 'ablog <command> -h' for more information on a specific command.
|
||
|
|
|
||
|
|
.. contents:: Here are all the things you can do:
|
||
|
|
:local:
|
||
|
|
:backlinks: top
|
||
|
|
|
||
|
|
.. _start:
|
||
|
|
|
||
|
|
Start a New Project
|
||
|
|
-------------------
|
||
|
|
|
||
|
|
``ablog start`` command is for quickly setting up a blog project.
|
||
|
|
See :ref:`quick-start` for how it works and what it prepares for you::
|
||
|
|
|
||
|
|
$ ablog start -h
|
||
|
|
usage: ablog start [-h]
|
||
|
|
|
||
|
|
Start a new blog project by answering a few questions. You will end up with a
|
||
|
|
configuration file and sample pages.
|
||
|
|
|
||
|
|
optional arguments:
|
||
|
|
-h, --help show this help message and exit
|
||
|
|
|
||
|
|
.. _build:
|
||
|
|
|
||
|
|
Build your Website
|
||
|
|
------------------
|
||
|
|
|
||
|
|
Running ``ablog build`` in your project folder builds your website HTML pages::
|
||
|
|
|
||
|
|
$ ablog build -h
|
||
|
|
usage: ablog build [-h] [-a] [-b BUILDER] [-s SOURCEDIR] [-w WEBSITE]
|
||
|
|
[-d DOCTREES] [-T] [-P]
|
||
|
|
|
||
|
|
Path options can be set in conf.py. Default values of paths are relative to
|
||
|
|
conf.py.
|
||
|
|
|
||
|
|
optional arguments:
|
||
|
|
-h, --help show this help message and exit
|
||
|
|
-a write all files; default is to only write new and changed
|
||
|
|
files
|
||
|
|
-b BUILDER builder to use, default `ablog_builder` or dirhtml
|
||
|
|
-s SOURCEDIR root path for source files, default is path to the folder that
|
||
|
|
contains conf.py
|
||
|
|
-w WEBSITE path for website, default is _website when `ablog_website` is
|
||
|
|
not set in conf.py
|
||
|
|
-d DOCTREES path for the cached environment and doctree files, default
|
||
|
|
.doctrees when `ablog_doctrees` is not set in conf.py
|
||
|
|
-T show full traceback on exception
|
||
|
|
-P run pdb on exception
|
||
|
|
|
||
|
|
Serve and View Locally
|
||
|
|
----------------------
|
||
|
|
|
||
|
|
Running ``ablog serve``, after building your website, will start a Python server and open up browser tab to view your website::
|
||
|
|
|
||
|
|
$ ablog serve -h
|
||
|
|
usage: ablog serve [-h] [-w WEBSITE] [-p PORT] [-n] [-r] [--patterns]
|
||
|
|
|
||
|
|
Serve options can be set in conf.py. Default values of paths are relative to
|
||
|
|
conf.py.
|
||
|
|
|
||
|
|
optional arguments:
|
||
|
|
-h, --help show this help message and exit
|
||
|
|
-w WEBSITE path for website, default is _website when `ablog_website` is
|
||
|
|
not set in conf.py
|
||
|
|
-p PORT port number for HTTP server; default is 8000
|
||
|
|
-n do not open website in a new browser tab
|
||
|
|
-r rebuild when a file matching patterns change or get added
|
||
|
|
--patterns patterns for triggering rebuilds
|
||
|
|
|
||
|
|
.. _deploy:
|
||
|
|
|
||
|
|
Deploy to GitHub Pages
|
||
|
|
----------------------
|
||
|
|
|
||
|
|
Running ``ablog deploy`` will push your website to GitHub::
|
||
|
|
|
||
|
|
$ ablog deploy -h
|
||
|
|
usage: ablog deploy [-h] [-w WEBSITE] [-p REPODIR] [-g GITHUB_PAGES]
|
||
|
|
[-m MESSAGE] [-f] [--push-quietly]
|
||
|
|
[--github-branch GITHUB_BRANCH] [--github-ssh]
|
||
|
|
[--github-token GITHUB_TOKEN] [--github-url GITHUB_URL]
|
||
|
|
|
||
|
|
Path options can be set in conf.py. Default values of paths are relative to
|
||
|
|
conf.py.
|
||
|
|
|
||
|
|
options:
|
||
|
|
-h, --help show this help message and exit
|
||
|
|
-w WEBSITE path for website, default is _website when
|
||
|
|
`ablog_website` is not set in conf.py
|
||
|
|
-p REPODIR path to the location of repository to be deployed, e.g.
|
||
|
|
`../username.github.io`, default is folder containing
|
||
|
|
`conf.py`
|
||
|
|
-g GITHUB_PAGES GitHub username for deploying to GitHub pages
|
||
|
|
-m MESSAGE commit message
|
||
|
|
-f overwrite last commit, i.e. `commit --amend; push -f`
|
||
|
|
--push-quietly be more quiet when pushing changes
|
||
|
|
--github-branch GITHUB_BRANCH
|
||
|
|
Branch to use. Default is 'master'.
|
||
|
|
--github-ssh use ssh when cloning website
|
||
|
|
--github-token GITHUB_TOKEN
|
||
|
|
environment variable name storing GitHub access token
|
||
|
|
--github-url GITHUB_URL
|
||
|
|
Custom GitHub URL. Useful when multiple accounts are
|
||
|
|
configured on the same machine. Default is:
|
||
|
|
git@github.com
|
||
|
|
|
||
|
|
|
||
|
|
Create a Post
|
||
|
|
-------------
|
||
|
|
|
||
|
|
Finally, ``ablog post`` will make a new post template file::
|
||
|
|
|
||
|
|
$ ablog post -h
|
||
|
|
usage: ablog post [-h] [-t TITLE] filename
|
||
|
|
|
||
|
|
positional arguments:
|
||
|
|
filename filename, e.g. my-nth-post (.rst appended)
|
||
|
|
|
||
|
|
optional arguments:
|
||
|
|
-h, --help show this help message and exit
|
||
|
|
-t TITLE post title; default is formed from filename
|
||
|
|
|
||
|
|
Clean Build Files
|
||
|
|
-----------------
|
||
|
|
|
||
|
|
In case you needed, running ``ablog clean`` will remove build files and do a deep clean with ``-D`` option::
|
||
|
|
|
||
|
|
$ ablog clean -h
|
||
|
|
usage: ablog clean [-h] [-d DOCTREES] [-w WEBSITE] [-D]
|
||
|
|
|
||
|
|
Path options can be set in conf.py. Default values of paths are relative to
|
||
|
|
conf.py.
|
||
|
|
|
||
|
|
optional arguments:
|
||
|
|
-h, --help show this help message and exit
|
||
|
|
-d DOCTREES path for the cached environment and doctree files, default
|
||
|
|
.doctrees when `ablog_doctrees` is not set in conf.py
|
||
|
|
-w WEBSITE path for website, default is _website when `ablog_website` is
|
||
|
|
not set in conf.py
|
||
|
|
-D deep clean, remove cached environment and doctree files
|
||
|
|
|
||
|
|
.. update:: Apr 7, 2015
|
||
|
|
|
||
|
|
Added ``ablog clean`` and ``ablog deploy`` commands.
|