-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathcontributing.html
More file actions
432 lines (312 loc) · 17.4 KB
/
contributing.html
File metadata and controls
432 lines (312 loc) · 17.4 KB
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
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Contribution Guide — nussl 1.0.0 documentation</title>
<script type="text/javascript" src="_static/js/modernizr.min.js"></script>
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/language_data.js"></script>
<script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/theme_overrides.css" type="text/css" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Changelog" href="changelog.html" />
<link rel="prev" title="Citing nussl" href="citation.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home"> nussl
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting Started</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="examples/examples.html">Examples</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="recipes/recipes.html">Recipes</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="api.html">API Documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="citation.html">Citing nussl</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Contribution Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#general">General</a></li>
<li class="toctree-l2"><a class="reference internal" href="#documentation">Documentation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#developing">Developing</a></li>
<li class="toctree-l3"><a class="reference internal" href="#deploying">Deploying</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#adding-your-own-algorithm">Adding your own algorithm</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">nussl</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> »</li>
<li>Contribution Guide</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/contributing.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<style>
/* CSS overrides for sphinx_rtd_theme */
/* 24px margin */
.nbinput.nblast.container,
.nboutput.nblast.container {
margin-bottom: 19px; /* padding has already 5px */
}
/* ... except between code cells! */
.nblast.container + .nbinput.container {
margin-top: -19px;
}
.admonition > p:before {
margin-right: 4px; /* make room for the exclamation icon */
}
/* Fix math alignment, see https://github.com/rtfd/sphinx_rtd_theme/pull/686 */
.math {
text-align: unset;
}
</style>
<div class="section" id="contribution-guide">
<h1>Contribution Guide<a class="headerlink" href="#contribution-guide" title="Permalink to this headline">¶</a></h1>
<div class="section" id="general">
<h2>General<a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h2>
<p>Contributions are welcome and encouraged for <em>nussl</em>. It is through a community effort that <em>nussl</em>
has become what it is. With that in mind, we would like to outline a few things about contributing
to <em>nussl</em> before you submit your next amazing pull request.</p>
<p>Contributing to <em>nussl</em> is just like contributing to any other open source project, for the
most part. The process is exactly the same for fixing bugs or adding utility functions: make
a pull request, write some tests, make sure all of the code is up to snuff, and it’ll be approved.</p>
</div>
<div class="section" id="documentation">
<h2>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h2>
<div class="section" id="developing">
<h3>Developing<a class="headerlink" href="#developing" title="Permalink to this headline">¶</a></h3>
<p>Documentation for <em>nussl</em> is built with Sphinx. The source code for making docs
is kept in the <code class="docutils literal notranslate"><span class="pre">docs/</span></code> folder. There are two parts to the documentation. The first
is API documentation which is maintained alongside the code. The second part is
tutorials and examples, which are maintained as Jupyter <em>notebooks</em> and compiled into
the docs via [nbsphinx](<a class="reference external" href="https://nbsphinx.readthedocs.io/en/0.5.1/">https://nbsphinx.readthedocs.io/en/0.5.1/</a>).</p>
<p>The installation requirements for maintaining docs are kept in <code class="docutils literal notranslate"><span class="pre">extra_requirements</span></code>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ pip install -r extra_requirements.txt
</pre></div>
</div>
<p>Also make sure that nussl itself is installed in your env by navigating to the top-level
<em>nussl</em> directory and running:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ pip install -e .
</pre></div>
</div>
<p>You will also need both of the following installed to edit or create new tutorials or examples:</p>
<ul class="simple">
<li><p>[Jupyter](<a class="reference external" href="https://jupyter.org/install">https://jupyter.org/install</a>)</p></li>
<li><p>[Pandoc](<a class="reference external" href="https://pandoc.org/installing.html">https://pandoc.org/installing.html</a>)</p></li>
</ul>
<p>Follow the links for installation instructions for each of these projects.
(You may need to pip install extra_requirements.txt outside a conda env so that the
jupyter extensions can register correctly.)</p>
<p>Notebooks are NOT kept in the docs repository as is, as notebooks are very
hard to keep track of in git diffs and can get very large. Instead, they are kept as only
[jupytext](<a class="reference external" href="https://jupytext.readthedocs.io/en/latest/index.html">https://jupytext.readthedocs.io/en/latest/index.html</a>) representations.
So to build new docs, one will have to keep a local copy of every notebook executed. The
only notebooks that get committed are the ones in <code class="docutils literal notranslate"><span class="pre">docs/recipes/</span></code>, as these require
access to large datasets and GPU resources. These are run once and committed in an
executed format to the repository from a specific machine.</p>
<p>So, to contribute a notebook demonstrating or explaining some facet of <em>nussl</em>, do the
following:</p>
<ol class="arabic">
<li><p>Before you begin, navigate to the <code class="docutils literal notranslate"><span class="pre">docs/</span></code> directory and execute all of the notebooks present
in the docs (this only has to happen once on your machine):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ make notebooks
</pre></div>
</div>
<p>This will find every <code class="docutils literal notranslate"><span class="pre">*.py</span></code> script in docs/examples and docs/tutorials, create the
associated notebook, execute the cells, and convert your notebook to HTML so you
can quickly see what it looks like without having to launch it in Jupyter notebook.
When you run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code>, the executed notebooks are used in the documentation.</p>
<p>To just make one notebook, run the following command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ python create_and_execute_notebook path/to/script.py # make just one notebook
</pre></div>
</div>
</li>
<li><p>To actually</p></li>
</ol>
<blockquote>
<div><dl>
<dt>Option 1: create a new notebook in either <code class="docutils literal notranslate"><span class="pre">tutorials</span></code> or <code class="docutils literal notranslate"><span class="pre">examples</span></code>. Work in the notebook</dt><dd><p>until you are satisfied with your explanation/demo. Note: your notebook is NOT yet
in version control!</p>
<p>Now run the following command on your notebook:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ jupytext --set-formats ipynb,py docs/path/to/notebook.ipynb
</pre></div>
</div>
<p>The light text representation of your notebook is now tracked by Git and it is
identical to your notebook, except for the outputs. Since your notebook is already
executed (manually), when you make the docs you’ll see it in there as long as you
do the next step:</p>
<p>Option 2: create a script that you will later link to a notebook. Work in this script
until you’re satisfied like above. Then when done with it, run:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ python create_and_execute_notebook path/to/script.py
</pre></div>
</div>
<p>to link the script with a notebook and an HTML file. If you so wish, you can work
entirely in a script and just check the HTML file in your browser to make sure
everything renders okay.</p>
</dd>
</dl>
</div></blockquote>
<ol class="arabic" start="3">
<li><p>Add your notebook to the toctree of the associated folder. For example,
<code class="docutils literal notranslate"><span class="pre">examples/primitives/primitives.rst</span></code> has the following contents:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Primitives
==========
.. toctree::
:maxdepth: 4
FT2D <2dft.py>
REPET <repet.py>
REPETSIM <repet_sim.py>
Melodia <melodia.py>
TimbreClustering <timbre.py>
HPSS <hpss.py>
</pre></div>
</div>
<p>So if you are adding examples for a new primitive algorithm, be sure to edit
this like so:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Primitives
==========
.. toctree::
:maxdepth: 4
FT2D <2dft.py>
REPET <repet.py>
REPETSIM <repet_sim.py>
Melodia <melodia.py>
TimbreClustering <timbre.py>
HPSS <hpss.py>
[Your algorithm] <path/to/light/script.py>
</pre></div>
</div>
</li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code> from the docs folder. Then look at <code class="docutils literal notranslate"><span class="pre">_build/html/index.html</span></code> to see
what got generated.</p></li>
<li><p>Finally, it’s best to run the light script from scratch to make sure it’s doing what
you expect:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ python create_and_execute_notebook path/to/your_script.py
</pre></div>
</div>
<p>Inspect the resultant HTML file to make sure it’s doing what you want. Then run
<code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code> again.</p>
</li>
</ol>
</div>
<div class="section" id="deploying">
<h3>Deploying<a class="headerlink" href="#deploying" title="Permalink to this headline">¶</a></h3>
<p>This process results in rich and interactive documentation but also results in
large files. For this reason, the actual compiled documentation is kept in a [separate
repository](<a class="reference external" href="https://github.com/nussl/docs">https://github.com/nussl/docs</a>), so that the main code repository stays
small. To deploy the documentation, first use the staging script. This script takes in
an as an argument the path to the cloned documentation repository (if the path does not
exist, then the documentation is cloned into that folder). It will first copy the contents of
<code class="docutils literal notranslate"><span class="pre">_build/html/</span></code> into the compiled docs repo. Then it will make a commit with update to
the docs. Then it will tell you to push the docs after a manual inspection of it. The
sequence of commands looks like this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python stage_docs.py path/to/docs/repo/
cd path/to/docs/repo
# inspect the docs by opening index.html in your browser
# make sure everything is okay
git push origin master
</pre></div>
</div>
<p>Then visit <a class="reference external" href="https://nussl.github.io/docs/">https://nussl.github.io/docs/</a> to make sure everything is okay.</p>
</div>
</div>
<div class="section" id="adding-your-own-algorithm">
<h2>Adding your own algorithm<a class="headerlink" href="#adding-your-own-algorithm" title="Permalink to this headline">¶</a></h2>
<p>The one place that our process differs from other open source projects is when contributing
new algorithms to <em>nussl</em>. After your algorithm is written, the developers of <em>nussl</em> ask that you
follow these additional steps when contributing it:</p>
<ol class="arabic simple" start="0">
<li><p>Code passes style and error checks. I.e., <em>Does it follow PEP8?</em>, <em>Can this code be run on any
machine without raising an exception?</em></p></li>
<li><p>Provide benchmark files for this new algorithm. These can be one or two audio files that
have passed through your algorithm. These files can be from established data sets or files
that are already of the External File Zoo (EFZ). We also ask that you provide expected output values
from one or more evaluation measures (BSS-Eval, etc).</p></li>
<li><p>If this algorithm existed somewhere else prior to this implementation, we would like a copy
of that implementation. This will be used to benchmark against.</p></li>
<li><p>If you are NOT the original author of the algorithm, we would like written permission
from the original author of the algorithm authorizing this implementation.</p></li>
<li><p>A reference to the academic paper that this algorithm originated from.</p></li>
<li><p>Any additional files, such as trained neural network weights, should also be provided, as these
extra files will be needed to put on the EFZ.</p></li>
</ol>
<p>If there are any questions, feel free to contact the authors via email or github.</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="changelog.html" class="btn btn-neutral float-right" title="Changelog" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="citation.html" class="btn btn-neutral float-left" title="Citing nussl" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2020, Ethan Manilow, Prem Seetharaman
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>