1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
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.
|
