-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdevelopment.html
148 lines (132 loc) · 8.27 KB
/
development.html
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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Developer information — xdapy 0.9.0 documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/print.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.9.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/theme_extras.js"></script>
<link rel="top" title="xdapy 0.9.0 documentation" href="index.html" />
<link rel="prev" title="Migration" href="migration.html" />
</head>
<body>
<div class="header"><h1 class="heading"><a href="index.html">
<span>xdapy 0.9.0 documentation</span></a></h1>
<h2 class="heading"><span>Developer information</span></h2>
</div>
<div class="topnav">
<p>
«  <a href="migration.html">Migration</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
</p>
</div>
<div class="content">
<div class="section" id="developer-information">
<span id="id1"></span><h1>Developer information<a class="headerlink" href="#developer-information" title="Permalink to this headline">¶</a></h1>
<div class="section" id="publishing-the-documentation">
<h2>Publishing the documentation<a class="headerlink" href="#publishing-the-documentation" title="Permalink to this headline">¶</a></h2>
<p>The documentation is built using <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> and published on github. In order to make the publishing process as easy as possible, we have included a shell script <tt class="docutils literal"><span class="pre">./commit-doc-tree.sh</span></tt> which automatically builds the documentation and creates a commit in a dedicated branch containing only the relevant data.</p>
<p>In order to use the script, we need to add the documentation repository (<a class="reference external" href="https://github.com/xdapy/xdapy.github.com">github.com/xdapy/xdapy.github.com</a>) to our local <em>xdapy</em> repository:</p>
<div class="highlight-python"><pre>$ git remote add github-docs [email protected]:xdapy/xdapy.github.com.git
$ git checkout --track -b gh-pages github-docs/master</pre>
</div>
<p>It is important to understand that we use a different name for our local branch. (For obvious reasons, we cannot not use the name <tt class="xref py py-obj docutils literal"><span class="pre">master</span></tt>.) Next, we should ensure that we automatically push to the correct branch:</p>
<div class="highlight-python"><pre>$ git config remote.github-docs.push gh-pages:master</pre>
</div>
<p>If we skip this step, we have to remember to always say <tt class="docutils literal"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">github-docs</span> <span class="pre">gh-pages:master</span></tt> when pushing.</p>
<p>Now we are ready to run the script:</p>
<div class="highlight-python"><pre>$ ./commit-doc-tree.sh --commit</pre>
</div>
<p>(If we leave out the <tt class="docutils literal"><span class="pre">--commit</span></tt> option, the script does a dry run and only builds the documentation without committing it.)</p>
<p>If all goes well, we get the following message:</p>
<div class="highlight-python"><pre>88afc9f DOC: Sphinx generated doc from master-001-g2d6557b
Committing succeeded. Now push to your remote repository:
git push github-docs gh-pages:master</pre>
</div>
<p>Therefore, all that is left to do is:</p>
<div class="highlight-python"><pre>git push github-docs gh-pages:master</pre>
</div>
<p>(Or simply <tt class="docutils literal"><span class="pre">git</span> <span class="pre">push</span></tt>, if we set the config option correctly.)</p>
</div>
<div class="section" id="commit-markers">
<h2>Commit Markers<a class="headerlink" href="#commit-markers" title="Permalink to this headline">¶</a></h2>
<p>Commits should be marked. Declare both functionality and area.</p>
<div class="section" id="functionality-markers">
<h3>Functionality Markers<a class="headerlink" href="#functionality-markers" title="Permalink to this headline">¶</a></h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name"><tt class="docutils literal"><span class="pre">BF</span></tt> or <tt class="docutils literal"><span class="pre">FIX</span></tt>:</th><td class="field-body">bug fix</td>
</tr>
<tr class="field-even field"><th class="field-name"><tt class="docutils literal"><span class="pre">RF</span></tt>:</th><td class="field-body">refactoring</td>
</tr>
<tr class="field-odd field"><th class="field-name"><tt class="docutils literal"><span class="pre">NF</span></tt>:</th><td class="field-body">new feature</td>
</tr>
<tr class="field-even field"><th class="field-name"><tt class="docutils literal"><span class="pre">ENH</span></tt>:</th><td class="field-body">enhancement of an existing feature/facility</td>
</tr>
<tr class="field-odd field"><th class="field-name"><tt class="docutils literal"><span class="pre">BW</span></tt>:</th><td class="field-body">addresses backward-compatibility</td>
</tr>
<tr class="field-even field"><th class="field-name"><tt class="docutils literal"><span class="pre">OPT</span></tt>:</th><td class="field-body">optimization</td>
</tr>
<tr class="field-odd field"><th class="field-name"><tt class="docutils literal"><span class="pre">BK</span></tt>:</th><td class="field-body">breaks something and/or tests fail</td>
</tr>
<tr class="field-even field"><th class="field-name"><tt class="docutils literal"><span class="pre">FO</span></tt>:</th><td class="field-body">code formatting (adding spaces etc.)</td>
</tr>
<tr class="field-odd field"><th class="field-name"><tt class="docutils literal"><span class="pre">PL</span></tt>:</th><td class="field-body">making pylint happier</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="code-area-markers">
<h3>Code Area Markers<a class="headerlink" href="#code-area-markers" title="Permalink to this headline">¶</a></h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name"><tt class="docutils literal"><span class="pre">DOC</span></tt>:</th><td class="field-body">documentation</td>
</tr>
<tr class="field-even field"><th class="field-name"><tt class="docutils literal"><span class="pre">UT</span></tt>:</th><td class="field-body">unit tests</td>
</tr>
<tr class="field-odd field"><th class="field-name"><tt class="docutils literal"><span class="pre">BLD</span></tt>:</th><td class="field-body">build-system, setup.py</td>
</tr>
<tr class="field-even field"><th class="field-name"><tt class="docutils literal"><span class="pre">GIT</span></tt>:</th><td class="field-body">repository mods, e.g. .gitconfig .gitattributes</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="example">
<h3>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">DOC/ENH:</span> <span class="pre">add</span> <span class="pre">initial</span> <span class="pre">README.md</span></tt></p>
</div>
</div>
</div>
</div>
<div class="bottomnav">
<p>
«  <a href="migration.html">Migration</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
</p>
</div>
<div class="footer">
© Copyright 2012, Hannah Dold, Rike-Benjamin Schuppner.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>