mirror of
https://github.com/wassname/catalyst.git
synced 2026-07-01 07:07:29 +08:00
AvishaiW
226 lines
13 KiB
HTML
226 lines
13 KiB
HTML
|
||
<!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>Development Guidelines — Catalyst 0.4 documentation</title>
|
||
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
|
||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||
<script type="text/javascript">
|
||
var DOCUMENTATION_OPTIONS = {
|
||
URL_ROOT: './',
|
||
VERSION: '0.4',
|
||
COLLAPSE_INDEX: false,
|
||
FILE_SUFFIX: '.html',
|
||
HAS_SOURCE: true,
|
||
SOURCELINK_SUFFIX: '.txt'
|
||
};
|
||
</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>
|
||
<link rel="index" title="Index" href="genindex.html" />
|
||
<link rel="search" title="Search" href="search.html" />
|
||
<link rel="next" title="Release Notes" href="releases.html" />
|
||
<link rel="prev" title="Resources" href="resources.html" />
|
||
</head>
|
||
<body>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="releases.html" title="Release Notes"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="resources.html" title="Resources"
|
||
accesskey="P">previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="index.html">Catalyst 0.4 documentation</a> »</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="development-guidelines">
|
||
<h1>Development Guidelines<a class="headerlink" href="#development-guidelines" title="Permalink to this headline">¶</a></h1>
|
||
<p>This page is intended for developers of Catalyst, people who want to contribute to the Catalyst codebase or documentation, or people who want to install from source and make local changes to their copy of Catalyst.</p>
|
||
<p>All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome. We <a class="reference external" href="https://github.com/enigmampc/catalyst/issues">track issues</a> on <a class="reference external" href="https://github.com/enigmampc/catalyst">GitHub</a> and also have a <a class="reference external" href="https://discord.gg/SJK32GY">discord group</a> where you can ask questions.</p>
|
||
<div class="section" id="creating-a-development-environment">
|
||
<h2>Creating a Development Environment<a class="headerlink" href="#creating-a-development-environment" title="Permalink to this headline">¶</a></h2>
|
||
<p>First, you’ll need to clone Catalyst by running:</p>
|
||
<div class="highlight-bash"><div class="highlight"><pre><span></span>$ git clone git@github.com:enigmampc/catalyst.git
|
||
</pre></div>
|
||
</div>
|
||
<p>Then check out to a new branch where you can make your changes:</p>
|
||
<div class="highlight-bash"><div class="highlight"><pre><span></span>$ git checkout -b some-short-descriptive-name
|
||
</pre></div>
|
||
</div>
|
||
<p>If you don’t already have them, you’ll need some C library dependencies. You can follow the <a class="reference external" href="install.html">install guide</a> to get the appropriate dependencies.</p>
|
||
<p>The following section assumes you already have virtualenvwrapper and pip installed on your system. Suggested installation of Python library dependencies used for development:</p>
|
||
<div class="highlight-bash"><div class="highlight"><pre><span></span>$ mkvirtualenv catalyst
|
||
$ ./etc/ordered_pip.sh ./etc/requirements.txt
|
||
$ pip install -r ./etc/requirements_dev.txt
|
||
$ pip install -r ./etc/requirements_blaze.txt
|
||
</pre></div>
|
||
</div>
|
||
<p>Finally, you can build the C extensions by running:</p>
|
||
<div class="highlight-bash"><div class="highlight"><pre><span></span>$ python setup.py build_ext --inplace
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="development-with-docker">
|
||
<h2>Development with Docker<a class="headerlink" href="#development-with-docker" title="Permalink to this headline">¶</a></h2>
|
||
<p>If you want to work with zipline using a <a class="reference external" href="https://docs.docker.com/get-started/">Docker</a> container, you’ll need to
|
||
build the <code class="docutils literal"><span class="pre">Dockerfile</span></code> in the Zipline root directory, and then build
|
||
<code class="docutils literal"><span class="pre">Dockerfile-dev</span></code>. Instructions for building both containers can be found in
|
||
<code class="docutils literal"><span class="pre">Dockerfile</span></code> and <code class="docutils literal"><span class="pre">Dockerfile-dev</span></code>, respectively.</p>
|
||
</div>
|
||
<div class="section" id="git-branching-structure">
|
||
<h2>Git Branching Structure<a class="headerlink" href="#git-branching-structure" title="Permalink to this headline">¶</a></h2>
|
||
<p>If you want to contribute to the codebase of Catalyst, familiarize yourself with our branching structure, a fairly standardized one for that matter, that follows what is documented in the following article: <a class="reference external" href="http://nvie.com/posts/a-successful-git-branching-model/">A successful Git branching model</a>. To contribute, create your local branch and submit a Pull Request (PR) to the <strong>develop</strong> branch.</p>
|
||
<img alt="https://camo.githubusercontent.com/9bde6fb64a9542a572e0e2017cbb58d9d2c440ac/687474703a2f2f6e7669652e636f6d2f696d672f6769742d6d6f64656c4032782e706e67" src="https://camo.githubusercontent.com/9bde6fb64a9542a572e0e2017cbb58d9d2c440ac/687474703a2f2f6e7669652e636f6d2f696d672f6769742d6d6f64656c4032782e706e67" />
|
||
</div>
|
||
<div class="section" id="contributing-to-the-docs">
|
||
<h2>Contributing to the Docs<a class="headerlink" href="#contributing-to-the-docs" title="Permalink to this headline">¶</a></h2>
|
||
<p>If you’d like to contribute to the documentation on enigmampc.github.io, you can navigate to <code class="docutils literal"><span class="pre">docs/source/</span></code> where each <a class="reference external" href="https://en.wikipedia.org/wiki/ReStructuredText">reStructuredText</a> file is a separate section there. To add a section, create a new file called <code class="docutils literal"><span class="pre">some-descriptive-name.rst</span></code> and add <code class="docutils literal"><span class="pre">some-descriptive-name</span></code> to <code class="docutils literal"><span class="pre">index.rst</span></code>. To edit a section, simply open up one of the existing files, make your changes, and save them.</p>
|
||
<p>We use <a class="reference external" href="http://www.sphinx-doc.org/en/stable/">Sphinx</a> to generate documentation for Catalyst, which you will need to install by running:</p>
|
||
<div class="highlight-bash"><div class="highlight"><pre><span></span>$ pip install -r ./etc/requirements_docs.txt
|
||
</pre></div>
|
||
</div>
|
||
<p>To build and view the docs locally, run:</p>
|
||
<div class="highlight-bash"><div class="highlight"><pre><span></span><span class="c1"># assuming you're in the Catalyst root directory</span>
|
||
$ <span class="nb">cd</span> docs
|
||
$ make html
|
||
$ <span class="o">{</span>BROWSER<span class="o">}</span> build/html/index.html
|
||
</pre></div>
|
||
</div>
|
||
<p>There is a <a class="reference external" href="https://github.com/sphinx-doc/sphinx/issues/3212">documented issue</a>
|
||
with <code class="docutils literal"><span class="pre">sphinx</span></code> and <code class="docutils literal"><span class="pre">docutils</span></code> that causes the error below when trying to build
|
||
the docs.</p>
|
||
<div class="highlight-text"><div class="highlight"><pre><span></span>Exception occurred:
|
||
File "(...)/env-c/lib/python2.7/site-packages/docutils/writers/_html_base.py", line 671, in depart_document
|
||
assert not self.context, 'len(context) = %s' % len(self.context)
|
||
AssertionError: len(context) = 3
|
||
</pre></div>
|
||
</div>
|
||
<p>If you get this error, you need to downgrade your version of <code class="docutils literal"><span class="pre">docutils</span></code> as
|
||
follows, and build the docs again:</p>
|
||
<div class="highlight-bash"><div class="highlight"><pre><span></span>$ pip install <span class="nv">docutils</span><span class="o">==</span><span class="m">0</span>.12
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="commit-messages">
|
||
<h2>Commit messages<a class="headerlink" href="#commit-messages" title="Permalink to this headline">¶</a></h2>
|
||
<p>Standard prefixes to start a commit message:</p>
|
||
<div class="highlight-text"><div class="highlight"><pre><span></span>BLD: change related to building Catalyst
|
||
BUG: bug fix
|
||
DEP: deprecate something, or remove a deprecated object
|
||
DEV: development tool or utility
|
||
DOC: documentation
|
||
ENH: enhancement
|
||
MAINT: maintenance commit (refactoring, typos, etc)
|
||
REV: revert an earlier commit
|
||
STY: style fix (whitespace, PEP8, flake8, etc)
|
||
TST: addition or modification of tests
|
||
REL: related to releasing Catalyst
|
||
PERF: performance enhancements
|
||
</pre></div>
|
||
</div>
|
||
<p>Some commit style guidelines:</p>
|
||
<p>Commit lines should be no longer than <a class="reference external" href="https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project">72 characters</a>. The first line of the commit should include one of the above prefixes. There should be an empty line between the commit subject and the body of the commit. In general, the message should be in the imperative tense. Best practice is to include not only what the change is, but why the change was made.</p>
|
||
<p><strong>Example:</strong></p>
|
||
<div class="highlight-text"><div class="highlight"><pre><span></span>MAINT: Remove unused calculations of max_leverage, et al.
|
||
|
||
In the performance period the max_leverage, max_capital_used,
|
||
cumulative_capital_used were calculated but not used.
|
||
|
||
At least one of those calculations, max_leverage, was causing a
|
||
divide by zero error.
|
||
|
||
Instead of papering over that error, the entire calculation was
|
||
a bit suspect so removing, with possibility of adding it back in
|
||
later with handling the case (or raising appropriate errors) when
|
||
the algorithm has little cash on hand.
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="formatting-docstrings">
|
||
<h2>Formatting Docstrings<a class="headerlink" href="#formatting-docstrings" title="Permalink to this headline">¶</a></h2>
|
||
<p>When adding or editing docstrings for classes, functions, etc, we use <a class="reference external" href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">numpy</a> as the canonical reference.</p>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="index.html">Table Of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Development Guidelines</a><ul>
|
||
<li><a class="reference internal" href="#creating-a-development-environment">Creating a Development Environment</a></li>
|
||
<li><a class="reference internal" href="#development-with-docker">Development with Docker</a></li>
|
||
<li><a class="reference internal" href="#git-branching-structure">Git Branching Structure</a></li>
|
||
<li><a class="reference internal" href="#contributing-to-the-docs">Contributing to the Docs</a></li>
|
||
<li><a class="reference internal" href="#commit-messages">Commit messages</a></li>
|
||
<li><a class="reference internal" href="#formatting-docstrings">Formatting Docstrings</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="resources.html"
|
||
title="previous chapter">Resources</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="releases.html"
|
||
title="next chapter">Release Notes</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="_sources/development-guidelines.rst.txt"
|
||
rel="nofollow">Show Source</a></li>
|
||
</ul>
|
||
</div>
|
||
<div id="searchbox" style="display: none" role="search">
|
||
<h3>Quick search</h3>
|
||
<form class="search" action="search.html" method="get">
|
||
<div><input type="text" name="q" /></div>
|
||
<div><input type="submit" value="Go" /></div>
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('#searchbox').show(0);</script>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="releases.html" title="Release Notes"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="resources.html" title="Resources"
|
||
>previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="index.html">Catalyst 0.4 documentation</a> »</li>
|
||
</ul>
|
||
</div>
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2018, Enigma MPC, Inc..
|
||
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.6.
|
||
</div>
|
||
</body>
|
||
</html> |