diff options
Diffstat (limited to 'docs/manual/ablog-commands.rst')
| -rw-r--r-- | docs/manual/ablog-commands.rst | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/docs/manual/ablog-commands.rst b/docs/manual/ablog-commands.rst new file mode 100644 index 0000000..c50cbd7 --- /dev/null +++ b/docs/manual/ablog-commands.rst @@ -0,0 +1,178 @@ +.. _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. |