Browse Source

Merge "Split README.rst into separate doc files"

tags/1.0.0
Jenkins 4 years ago
parent
commit
4158150c48
12 changed files with 647 additions and 167 deletions
  1. 1
    0
      .gitignore
  2. 22
    0
      CONTRIBUTING.rst
  3. 4
    167
      README.rst
  4. 177
    0
      doc/Makefile
  5. 252
    0
      doc/source/conf.py
  6. 23
    0
      doc/source/developing.rst
  7. 22
    0
      doc/source/index.rst
  8. 85
    0
      doc/source/installation.rst
  9. 47
    0
      doc/source/usage.rst
  10. 8
    0
      setup.cfg
  11. 2
    0
      test-requirements.txt
  12. 4
    0
      tox.ini

+ 1
- 0
.gitignore View File

@@ -11,3 +11,4 @@ ChangeLog
11 11
 *.egg
12 12
 *.egg-info
13 13
 *.pyc
14
+doc/build

+ 22
- 0
CONTRIBUTING.rst View File

@@ -0,0 +1,22 @@
1
+============================
2
+ Contributing to git-review
3
+============================
4
+
5
+To get the latest code, see: https://git.openstack.org/cgit/openstack-infra/git-review
6
+
7
+Bugs are handled at: https://storyboard.openstack.org/#!/project/719
8
+
9
+There is a mailing list at: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra
10
+
11
+Code reviews, as you might expect, are handled by gerrit at:
12
+https://review.openstack.org
13
+
14
+See http://wiki.openstack.org/GerritWorkflow for details. Pull
15
+requests submitted through GitHub will be ignored.
16
+
17
+Use ``git review`` to submit patches (after creating a gerrit account
18
+that links to your launchpad account). Example::
19
+
20
+    # Do your commits
21
+    git review
22
+    # Enter your username if prompted

+ 4
- 167
README.rst View File

@@ -6,170 +6,7 @@ A git command for submitting branches to Gerrit
6 6
 git-review is a tool that helps submitting git branches to gerrit for
7 7
 review.
8 8
 
9
-Setup
10
------
11
-
12
-By default, git-review will look for a remote named 'gerrit' for working
13
-with Gerrit. If the remote exists, git-review will submit the current
14
-branch to HEAD:refs/for/master at that remote.
15
-
16
-If the Gerrit remote does not exist, git-review looks for a file
17
-called .gitreview at the root of the repository with information about
18
-the gerrit remote.  Assuming that file is present, git-review should
19
-be able to automatically configure your repository the first time it
20
-is run.
21
-
22
-The name of the Gerrit remote is configurable; see the configuration
23
-section below.
24
-
25
-Usage
26
------
27
-
28
-Hack on some code, then::
29
-
30
-    git review
31
-
32
-If you want to submit that code to a branch other than "master", then::
33
-
34
-    git review branchname
35
-
36
-If you want to submit to a different remote::
37
-
38
-    git review -r my-remote
39
-
40
-If you want to supply a review topic::
41
-
42
-    git review -t topic/awesome-feature
43
-
44
-If you want to disable autogenerated topic::
45
-
46
-    git review -T
47
-
48
-If you want to submit a branch for review and then remove the local branch::
49
-
50
-    git review -f
51
-
52
-If you want to skip the automatic "git rebase -i" step::
53
-
54
-    git review -R
55
-
56
-If you want to download change 781 from gerrit to review it::
57
-
58
-    git review -d 781
59
-
60
-If you want to download patchset 4 for change 781 from gerrit to review it::
61
-
62
-    git review -d 781,4
63
-
64
-If you want to compare patchset 4 with patchset 10 of change 781 from gerrit::
65
-
66
-    git review -m 781,4-10
67
-
68
-If you just want to do the commit message and remote setup steps::
69
-
70
-    git review -s
71
-
72
-.gitreview file format
73
-----------------------
74
-
75
-Example .gitreview file (used to upload for git-review itself)::
76
-
77
-    [gerrit]
78
-    host=review.openstack.org
79
-    port=29418
80
-    project=openstack-infra/git-review.git
81
-    defaultbranch=master
82
-
83
-Required values: host, project
84
-
85
-Optional values: port (default: 29418), defaultbranch (default: master),
86
-defaultremote (default: gerrit).
87
-
88
-**Notes**
89
-
90
-* Username is not required because it is requested on first run
91
-
92
-* Unlike git config files, there cannot be any whitespace before the name
93
-  of the variable.
94
-
95
-* Upon first run, git-review will create a remote for working with Gerrit,
96
-  if it does not already exist. By default, the remote name is 'gerrit',
97
-  but this can be overridden with the 'defaultremote' configuration
98
-  option.
99
-
100
-* You can specify different values to be used as defaults in
101
-  ~/.config/git-review/git-review.conf or /etc/git-review/git-review.conf.
102
-
103
-Hooks
104
------
105
-
106
-git-review has a custom hook mechanism to run a script before certain
107
-actions. This is done in the same spirit as the classic hooks in git.
108
-
109
-There are two types of hooks, a global one which is stored in
110
-~/.config/git-review/hooks/ and one local to the repository stored in
111
-.git/hooks/ with the other git hook scripts.
112
-
113
-**The script needs be executable before getting executed**
114
-
115
-The name of the script is $action-review where action can be
116
-:
117
-
118
-* pre - run at first before doing anything.
119
-
120
-* post - run at the end after the review was sent.
121
-
122
-* draft - run when in draft mode.
123
-
124
-if the script returns with an exit status different than zero,
125
-git-review will exit with the a custom shell exit code 71.
126
-
127
-Installation
128
-------------
129
-
130
-Install with pip install git-review
131
-
132
-For assistance installing pip on your os check out get-pip:
133
-http://pip.readthedocs.org/en/latest/installing.html
134
-
135
-For installation from source simply add git-review to your $PATH
136
-after installing the dependencies listed in requirements.txt
137
-
138
-Running tests
139
--------------
140
-
141
-Running tests for git-review means running a local copy of Gerrit to
142
-check that git-review interacts correctly with it. This requires the
143
-following:
144
-
145
-* a Java Runtime Environment on the machine to run tests on
146
-
147
-* Internet access to download the gerrit.war file, or a locally
148
-  cached copy (it needs to be located in a .gerrit directory at the
149
-  top level of the git-review project)
150
-
151
-To run git-review integration tests the following commands may by run::
152
-
153
-    tox -e py27
154
-    tox -e py26
155
-    tox -e py32
156
-    tox -e py33
157
-
158
-depending on what Python interpreter would you like to use.
159
-
160
-Contributing
161
-------------
162
-
163
-To get the latest code, see: https://git.openstack.org/cgit/openstack-infra/git-review
164
-
165
-Bugs are handled at: https://storyboard.openstack.org/#!/project/719
166
-
167
-There is a mailing list at: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra
168
-
169
-Code reviews, as you might expect, are handled by gerrit at: https://review.openstack.org
170
-
171
-Use ``git review`` to submit patches (after creating a gerrit account that links to your launchpad account). Example::
172
-
173
-    # Do your commits
174
-    git review
175
-    # Enter your username if prompted
9
+* Free software: Apache license
10
+* Documentation: http://docs.openstack.org/developer/git-review
11
+* Source: https://git.openstack.org/cgit/openstack-infra/git-review
12
+* Bugs: https://storyboard.openstack.org/#!/project/719

+ 177
- 0
doc/Makefile View File

@@ -0,0 +1,177 @@
1
+# Makefile for Sphinx documentation
2
+#
3
+
4
+# You can set these variables from the command line.
5
+SPHINXOPTS    =
6
+SPHINXBUILD   = sphinx-build
7
+PAPER         =
8
+BUILDDIR      = build
9
+
10
+# User-friendly check for sphinx-build
11
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
12
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
13
+endif
14
+
15
+# Internal variables.
16
+PAPEROPT_a4     = -D latex_paper_size=a4
17
+PAPEROPT_letter = -D latex_paper_size=letter
18
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
19
+# the i18n builder cannot share the environment and doctrees with the others
20
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
21
+
22
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
23
+
24
+help:
25
+	@echo "Please use \`make <target>' where <target> is one of"
26
+	@echo "  html       to make standalone HTML files"
27
+	@echo "  dirhtml    to make HTML files named index.html in directories"
28
+	@echo "  singlehtml to make a single large HTML file"
29
+	@echo "  pickle     to make pickle files"
30
+	@echo "  json       to make JSON files"
31
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
32
+	@echo "  qthelp     to make HTML files and a qthelp project"
33
+	@echo "  devhelp    to make HTML files and a Devhelp project"
34
+	@echo "  epub       to make an epub"
35
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
36
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
37
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
38
+	@echo "  text       to make text files"
39
+	@echo "  man        to make manual pages"
40
+	@echo "  texinfo    to make Texinfo files"
41
+	@echo "  info       to make Texinfo files and run them through makeinfo"
42
+	@echo "  gettext    to make PO message catalogs"
43
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
44
+	@echo "  xml        to make Docutils-native XML files"
45
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
46
+	@echo "  linkcheck  to check all external links for integrity"
47
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
48
+
49
+clean:
50
+	rm -rf $(BUILDDIR)/*
51
+
52
+html:
53
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
54
+	@echo
55
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
56
+
57
+dirhtml:
58
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
59
+	@echo
60
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
61
+
62
+singlehtml:
63
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
64
+	@echo
65
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
66
+
67
+pickle:
68
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
69
+	@echo
70
+	@echo "Build finished; now you can process the pickle files."
71
+
72
+json:
73
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
74
+	@echo
75
+	@echo "Build finished; now you can process the JSON files."
76
+
77
+htmlhelp:
78
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
79
+	@echo
80
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
81
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
82
+
83
+qthelp:
84
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
85
+	@echo
86
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
87
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
88
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/git-review.qhcp"
89
+	@echo "To view the help file:"
90
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/git-review.qhc"
91
+
92
+devhelp:
93
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
94
+	@echo
95
+	@echo "Build finished."
96
+	@echo "To view the help file:"
97
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/git-review"
98
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/git-review"
99
+	@echo "# devhelp"
100
+
101
+epub:
102
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
103
+	@echo
104
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
105
+
106
+latex:
107
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
108
+	@echo
109
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
110
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
111
+	      "(use \`make latexpdf' here to do that automatically)."
112
+
113
+latexpdf:
114
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
115
+	@echo "Running LaTeX files through pdflatex..."
116
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
117
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
118
+
119
+latexpdfja:
120
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
121
+	@echo "Running LaTeX files through platex and dvipdfmx..."
122
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
123
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
124
+
125
+text:
126
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
127
+	@echo
128
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
129
+
130
+man:
131
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
132
+	@echo
133
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
134
+
135
+texinfo:
136
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
137
+	@echo
138
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
139
+	@echo "Run \`make' in that directory to run these through makeinfo" \
140
+	      "(use \`make info' here to do that automatically)."
141
+
142
+info:
143
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
144
+	@echo "Running Texinfo files through makeinfo..."
145
+	make -C $(BUILDDIR)/texinfo info
146
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
147
+
148
+gettext:
149
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
150
+	@echo
151
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
152
+
153
+changes:
154
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
155
+	@echo
156
+	@echo "The overview file is in $(BUILDDIR)/changes."
157
+
158
+linkcheck:
159
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
160
+	@echo
161
+	@echo "Link check complete; look for any errors in the above output " \
162
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
163
+
164
+doctest:
165
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
166
+	@echo "Testing of doctests in the sources finished, look at the " \
167
+	      "results in $(BUILDDIR)/doctest/output.txt."
168
+
169
+xml:
170
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
171
+	@echo
172
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
173
+
174
+pseudoxml:
175
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
176
+	@echo
177
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

+ 252
- 0
doc/source/conf.py View File

@@ -0,0 +1,252 @@
1
+# -*- coding: utf-8 -*-
2
+#
3
+# git-review documentation build configuration file, created by
4
+# sphinx-quickstart on Mon Dec  1 14:06:22 2014.
5
+#
6
+# This file is execfile()d with the current directory set to its
7
+# containing dir.
8
+#
9
+# Note that not all possible configuration values are present in this
10
+# autogenerated file.
11
+#
12
+# All configuration values have a default; values that are commented out
13
+# serve to show the default.
14
+
15
+import sys
16
+import os
17
+
18
+# If extensions (or modules to document with autodoc) are in another directory,
19
+# add these directories to sys.path here. If the directory is relative to the
20
+# documentation root, use os.path.abspath to make it absolute, like shown here.
21
+#sys.path.insert(0, os.path.abspath('.'))
22
+
23
+# -- General configuration ------------------------------------------------
24
+
25
+# If your documentation needs a minimal Sphinx version, state it here.
26
+#needs_sphinx = '1.0'
27
+
28
+# Add any Sphinx extension module names here, as strings. They can be
29
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
30
+# ones.
31
+extensions = [
32
+    'sphinx.ext.autodoc',
33
+    'oslosphinx',
34
+]
35
+
36
+# Add any paths that contain templates here, relative to this directory.
37
+templates_path = ['_templates']
38
+
39
+# The suffix of source filenames.
40
+source_suffix = '.rst'
41
+
42
+# The encoding of source files.
43
+#source_encoding = 'utf-8-sig'
44
+
45
+# The master toctree document.
46
+master_doc = 'index'
47
+
48
+# General information about the project.
49
+project = u'git-review'
50
+copyright = u'2014, OpenStack Contributors'
51
+
52
+# The language for content autogenerated by Sphinx. Refer to documentation
53
+# for a list of supported languages.
54
+#language = None
55
+
56
+# There are two options for replacing |today|: either, you set today to some
57
+# non-false value, then it is used:
58
+#today = ''
59
+# Else, today_fmt is used as the format for a strftime call.
60
+#today_fmt = '%B %d, %Y'
61
+
62
+# List of patterns, relative to source directory, that match files and
63
+# directories to ignore when looking for source files.
64
+exclude_patterns = []
65
+
66
+# The reST default role (used for this markup: `text`) to use for all
67
+# documents.
68
+#default_role = None
69
+
70
+# If true, '()' will be appended to :func: etc. cross-reference text.
71
+#add_function_parentheses = True
72
+
73
+# If true, the current module name will be prepended to all description
74
+# unit titles (such as .. function::).
75
+#add_module_names = True
76
+
77
+# If true, sectionauthor and moduleauthor directives will be shown in the
78
+# output. They are ignored by default.
79
+#show_authors = False
80
+
81
+# The name of the Pygments (syntax highlighting) style to use.
82
+pygments_style = 'sphinx'
83
+
84
+# A list of ignored prefixes for module index sorting.
85
+#modindex_common_prefix = []
86
+
87
+# If true, keep warnings as "system message" paragraphs in the built documents.
88
+#keep_warnings = False
89
+
90
+
91
+# -- Options for HTML output ----------------------------------------------
92
+
93
+# The theme to use for HTML and HTML Help pages.  See the documentation for
94
+# a list of builtin themes.
95
+html_theme = 'default'
96
+
97
+# Theme options are theme-specific and customize the look and feel of a theme
98
+# further.  For a list of options available for each theme, see the
99
+# documentation.
100
+#html_theme_options = {}
101
+
102
+# Add any paths that contain custom themes here, relative to this directory.
103
+#html_theme_path = []
104
+
105
+# The name for this set of Sphinx documents.  If None, it defaults to
106
+# "<project> v<release> documentation".
107
+#html_title = None
108
+
109
+# A shorter title for the navigation bar.  Default is the same as html_title.
110
+#html_short_title = None
111
+
112
+# The name of an image file (relative to this directory) to place at the top
113
+# of the sidebar.
114
+#html_logo = None
115
+
116
+# The name of an image file (within the static path) to use as favicon of the
117
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
118
+# pixels large.
119
+#html_favicon = None
120
+
121
+# Add any paths that contain custom static files (such as style sheets) here,
122
+# relative to this directory. They are copied after the builtin static files,
123
+# so a file named "default.css" will overwrite the builtin "default.css".
124
+# html_static_path = ['_static']
125
+
126
+# Add any extra paths that contain custom files (such as robots.txt or
127
+# .htaccess) here, relative to this directory. These files are copied
128
+# directly to the root of the documentation.
129
+#html_extra_path = []
130
+
131
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
132
+# using the given strftime format.
133
+#html_last_updated_fmt = '%b %d, %Y'
134
+
135
+# If true, SmartyPants will be used to convert quotes and dashes to
136
+# typographically correct entities.
137
+#html_use_smartypants = True
138
+
139
+# Custom sidebar templates, maps document names to template names.
140
+#html_sidebars = {}
141
+
142
+# Additional templates that should be rendered to pages, maps page names to
143
+# template names.
144
+#html_additional_pages = {}
145
+
146
+# If false, no module index is generated.
147
+#html_domain_indices = True
148
+
149
+# If false, no index is generated.
150
+#html_use_index = True
151
+
152
+# If true, the index is split into individual pages for each letter.
153
+#html_split_index = False
154
+
155
+# If true, links to the reST sources are added to the pages.
156
+#html_show_sourcelink = True
157
+
158
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
159
+#html_show_sphinx = True
160
+
161
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
162
+#html_show_copyright = True
163
+
164
+# If true, an OpenSearch description file will be output, and all pages will
165
+# contain a <link> tag referring to it.  The value of this option must be the
166
+# base URL from which the finished HTML is served.
167
+#html_use_opensearch = ''
168
+
169
+# This is the file name suffix for HTML files (e.g. ".xhtml").
170
+#html_file_suffix = None
171
+
172
+# Output file base name for HTML help builder.
173
+htmlhelp_basename = 'git-reviewdoc'
174
+
175
+
176
+# -- Options for LaTeX output ---------------------------------------------
177
+
178
+latex_elements = {
179
+# The paper size ('letterpaper' or 'a4paper').
180
+#'papersize': 'letterpaper',
181
+
182
+# The font size ('10pt', '11pt' or '12pt').
183
+#'pointsize': '10pt',
184
+
185
+# Additional stuff for the LaTeX preamble.
186
+#'preamble': '',
187
+}
188
+
189
+# Grouping the document tree into LaTeX files. List of tuples
190
+# (source start file, target name, title,
191
+#  author, documentclass [howto, manual, or own class]).
192
+latex_documents = [
193
+  ('index', 'git-review.tex', u'git-review Documentation',
194
+   u'OpenStack Contributors', 'manual'),
195
+]
196
+
197
+# The name of an image file (relative to this directory) to place at the top of
198
+# the title page.
199
+#latex_logo = None
200
+
201
+# For "manual" documents, if this is true, then toplevel headings are parts,
202
+# not chapters.
203
+#latex_use_parts = False
204
+
205
+# If true, show page references after internal links.
206
+#latex_show_pagerefs = False
207
+
208
+# If true, show URL addresses after external links.
209
+#latex_show_urls = False
210
+
211
+# Documents to append as an appendix to all manuals.
212
+#latex_appendices = []
213
+
214
+# If false, no module index is generated.
215
+#latex_domain_indices = True
216
+
217
+
218
+# -- Options for manual page output ---------------------------------------
219
+
220
+# One entry per manual page. List of tuples
221
+# (source start file, name, description, authors, manual section).
222
+man_pages = [
223
+    ('index', 'git-review', u'git-review Documentation',
224
+     [u'OpenStack Contributors'], 1)
225
+]
226
+
227
+# If true, show URL addresses after external links.
228
+#man_show_urls = False
229
+
230
+
231
+# -- Options for Texinfo output -------------------------------------------
232
+
233
+# Grouping the document tree into Texinfo files. List of tuples
234
+# (source start file, target name, title, author,
235
+#  dir menu entry, description, category)
236
+texinfo_documents = [
237
+  ('index', 'git-review', u'git-review Documentation',
238
+   u'OpenStack Contributors', 'git-review', 'One line description of project.',
239
+   'Miscellaneous'),
240
+]
241
+
242
+# Documents to append as an appendix to all manuals.
243
+#texinfo_appendices = []
244
+
245
+# If false, no module index is generated.
246
+#texinfo_domain_indices = True
247
+
248
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
249
+#texinfo_show_urls = 'footnote'
250
+
251
+# If true, do not generate a @detailmenu in the "Top" node's menu.
252
+#texinfo_no_detailmenu = False

+ 23
- 0
doc/source/developing.rst View File

@@ -0,0 +1,23 @@
1
+.. include:: ../../CONTRIBUTING.rst
2
+
3
+Running tests
4
+=============
5
+
6
+Running tests for git-review means running a local copy of Gerrit to
7
+check that git-review interacts correctly with it. This requires the
8
+following:
9
+
10
+* a Java Runtime Environment on the machine to run tests on
11
+
12
+* Internet access to download the gerrit.war file, or a locally
13
+  cached copy (it needs to be located in a .gerrit directory at the
14
+  top level of the git-review project)
15
+
16
+To run git-review integration tests the following commands may by run::
17
+
18
+    tox -e py27
19
+    tox -e py26
20
+    tox -e py32
21
+    tox -e py33
22
+
23
+depending on what Python interpreter would you like to use.

+ 22
- 0
doc/source/index.rst View File

@@ -0,0 +1,22 @@
1
+============
2
+ git-review
3
+============
4
+
5
+``git-review`` is a tool that helps submitting git branches to gerrit
6
+for review.
7
+
8
+.. toctree::
9
+   :maxdepth: 2
10
+
11
+   installation
12
+   usage
13
+   developing
14
+
15
+
16
+Indices and tables
17
+==================
18
+
19
+* :ref:`genindex`
20
+* :ref:`modindex`
21
+* :ref:`search`
22
+

+ 85
- 0
doc/source/installation.rst View File

@@ -0,0 +1,85 @@
1
+================================
2
+ Installation and Configuration
3
+================================
4
+
5
+Installing git-review
6
+=====================
7
+
8
+Install with pip install git-review
9
+
10
+For assistance installing pip on your os check out get-pip:
11
+http://pip.readthedocs.org/en/latest/installing.html
12
+
13
+For installation from source simply add git-review to your $PATH
14
+after installing the dependencies listed in requirements.txt
15
+
16
+Setup
17
+=====
18
+
19
+By default, git-review will look for a remote named 'gerrit' for working
20
+with Gerrit. If the remote exists, git-review will submit the current
21
+branch to HEAD:refs/for/master at that remote.
22
+
23
+If the Gerrit remote does not exist, git-review looks for a file
24
+called .gitreview at the root of the repository with information about
25
+the gerrit remote.  Assuming that file is present, git-review should
26
+be able to automatically configure your repository the first time it
27
+is run.
28
+
29
+The name of the Gerrit remote is configurable; see the configuration
30
+section below.
31
+
32
+.gitreview file format
33
+======================
34
+
35
+Example .gitreview file (used to upload for git-review itself)::
36
+
37
+    [gerrit]
38
+    host=review.openstack.org
39
+    port=29418
40
+    project=openstack-infra/git-review.git
41
+    defaultbranch=master
42
+
43
+Required values: host, project
44
+
45
+Optional values: port (default: 29418), defaultbranch (default: master),
46
+defaultremote (default: gerrit).
47
+
48
+**Notes**
49
+
50
+* Username is not required because it is requested on first run
51
+
52
+* Unlike git config files, there cannot be any whitespace before the name
53
+  of the variable.
54
+
55
+* Upon first run, git-review will create a remote for working with Gerrit,
56
+  if it does not already exist. By default, the remote name is 'gerrit',
57
+  but this can be overridden with the 'defaultremote' configuration
58
+  option.
59
+
60
+* You can specify different values to be used as defaults in
61
+  ~/.config/git-review/git-review.conf or /etc/git-review/git-review.conf.
62
+
63
+Hooks
64
+=====
65
+
66
+git-review has a custom hook mechanism to run a script before certain
67
+actions. This is done in the same spirit as the classic hooks in git.
68
+
69
+There are two types of hooks, a global one which is stored in
70
+~/.config/git-review/hooks/ and one local to the repository stored in
71
+.git/hooks/ with the other git hook scripts.
72
+
73
+**The script needs be executable before getting executed**
74
+
75
+The name of the script is $action-review where action can be
76
+:
77
+
78
+* pre - run at first before doing anything.
79
+
80
+* post - run at the end after the review was sent.
81
+
82
+* draft - run when in draft mode.
83
+
84
+if the script returns with an exit status different than zero,
85
+git-review will exit with the a custom shell exit code 71.

+ 47
- 0
doc/source/usage.rst View File

@@ -0,0 +1,47 @@
1
+=======
2
+ Usage
3
+=======
4
+
5
+Hack on some code, then::
6
+
7
+    git review
8
+
9
+If you want to submit that code to a branch other than "master", then::
10
+
11
+    git review branchname
12
+
13
+If you want to submit to a different remote::
14
+
15
+    git review -r my-remote
16
+
17
+If you want to supply a review topic::
18
+
19
+    git review -t topic/awesome-feature
20
+
21
+If you want to disable autogenerated topic::
22
+
23
+    git review -T
24
+
25
+If you want to submit a branch for review and then remove the local branch::
26
+
27
+    git review -f
28
+
29
+If you want to skip the automatic "git rebase -i" step::
30
+
31
+    git review -R
32
+
33
+If you want to download change 781 from gerrit to review it::
34
+
35
+    git review -d 781
36
+
37
+If you want to download patchset 4 for change 781 from gerrit to review it::
38
+
39
+    git review -d 781,4
40
+
41
+If you want to compare patchset 4 with patchset 10 of change 781 from gerrit::
42
+
43
+    git review -m 781,4-10
44
+
45
+If you just want to do the commit message and remote setup steps::
46
+
47
+    git review -s

+ 8
- 0
setup.cfg View File

@@ -29,3 +29,11 @@ console_scripts =
29 29
 
30 30
 [wheel]
31 31
 universal = 1
32
+
33
+[build_sphinx]
34
+source-dir = doc/source
35
+build-dir = doc/build
36
+all_files = 1
37
+
38
+[pbr]
39
+warnerrors = True

+ 2
- 0
test-requirements.txt View File

@@ -4,3 +4,5 @@ mock
4 4
 fixtures>=0.3.14
5 5
 testrepository>=0.0.18
6 6
 testtools>=0.9.34
7
+oslosphinx
8
+sphinx>=1.1.2,!=1.2.0,<1.3

+ 4
- 0
tox.ini View File

@@ -2,6 +2,7 @@
2 2
 envlist = py26,py27,py32,py33,py34,pep8
3 3
 
4 4
 [testenv]
5
+install_command = pip install -U {opts} {packages}
5 6
 setenv =
6 7
     VIRTUAL_ENV={envdir}
7 8
 
@@ -19,6 +20,9 @@ commands = flake8
19 20
 [testenv:sdist]
20 21
 commands = python setup.py sdist {posargs}
21 22
 
23
+[testenv:docs]
24
+commands = python setup.py build_sphinx
25
+
22 26
 [testenv:venv]
23 27
 commands = {posargs}
24 28
 

Loading…
Cancel
Save