-
Notifications
You must be signed in to change notification settings - Fork 0
nussl/docs
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
<!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 readthedocs/sphinx_rtd_theme#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>About
Documentation for nussl.
Contributing
Stars
Watchers
Forks
Releases
No releases published
Packages 0
No packages published