diff --git a/docs/source/development-guidelines.rst b/docs/source/development-guidelines.rst index d643090d..9bc6c7b0 100644 --- a/docs/source/development-guidelines.rst +++ b/docs/source/development-guidelines.rst @@ -1,21 +1,17 @@ Development Guidelines ====================== -This page is intended for developers of Zipline, people who want to contribute to the Zipline codebase or documentation, or people who want to install from source and make local changes to their copy of Zipline. +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. -All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome. We `track issues`__ on `GitHub`__ and also have a `mailing list`__ where you can ask questions. - -__ https://github.com/quantopian/zipline/issues -__ https://github.com/ -__ https://groups.google.com/forum/#!forum/zipline +All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome. We `track issues `_ on `GitHub `_ and also have a `discord group `_ where you can ask questions. Creating a Development Environment ---------------------------------- -First, you'll need to clone Zipline by running: +First, you'll need to clone Catalyst by running: .. code-block:: bash - $ git clone git@github.com:your-github-username/zipline.git + $ git clone git@github.com:enigmampc/catalyst.git Then check out to a new branch where you can make your changes: @@ -23,15 +19,13 @@ Then check out to a new branch where you can make your changes: $ git checkout -b some-short-descriptive-name -If you don't already have them, you'll need some C library dependencies. You can follow the `install guide`__ to get the appropriate dependencies. - -__ install.html +If you don't already have them, you'll need some C library dependencies. You can follow the `install guide `_ to get the appropriate dependencies. The following section assumes you already have virtualenvwrapper and pip installed on your system. Suggested installation of Python library dependencies used for development: .. code-block:: bash - $ mkvirtualenv zipline + $ mkvirtualenv catalyst $ ./etc/ordered_pip.sh ./etc/requirements.txt $ pip install -r ./etc/requirements_dev.txt $ pip install -r ./etc/requirements_blaze.txt @@ -42,104 +36,39 @@ Finally, you can build the C extensions by running: $ python setup.py build_ext --inplace -To finish, make sure `tests`__ pass. +.. To finish, make sure `tests`__ pass. -__ #style-guide-running-tests +.. __ #style-guide-running-tests -If you get an error running nosetests after setting up a fresh virtualenv, please try running +.. If you get an error running nosetests after setting up a fresh virtualenv, please try running -.. code-block:: bash +.. code-block - # where zipline is the name of your virtualenv - $ deactivate zipline - $ workon zipline +.. # where zipline is the name of your virtualenv +.. $ deactivate zipline +.. $ workon zipline -Development with Docker +.. Development with Docker +.. ----------------------- + +..If you want to work with zipline using a `Docker`__ container, you'll need to build the ``Dockerfile`` in the Zipline root directory, and then build ``Dockerfile-dev``. Instructions for building both containers can be found in ``Dockerfile`` and ``Dockerfile-dev``, respectively. + +.. __ https://docs.docker.com/get-started/ + +Git Branching Structure ----------------------- -If you want to work with zipline using a `Docker`__ container, you'll need to build the ``Dockerfile`` in the Zipline root directory, and then build ``Dockerfile-dev``. Instructions for building both containers can be found in ``Dockerfile`` and ``Dockerfile-dev``, respectively. +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 successful Git branching model `_. To contribute, create your local branch and submit a Pull Request (PR) to the **develop** branch. -__ https://docs.docker.com/get-started/ +.. image:: https://camo.githubusercontent.com/9bde6fb64a9542a572e0e2017cbb58d9d2c440ac/687474703a2f2f6e7669652e636f6d2f696d672f6769742d6d6f64656c4032782e706e67 - -Style Guide & Running Tests ---------------------------- - -We use `flake8`__ for checking style requirements and `nosetests`__ to run Zipline tests. Our `continuous integration`__ tools will run these commands. - -__ http://flake8.pycqa.org/en/latest/ -__ http://nose.readthedocs.io/en/latest/ -__ https://en.wikipedia.org/wiki/Continuous_integration - -Before submitting patches or pull requests, please ensure that your changes pass when running: - -.. code-block:: bash - - $ flake8 zipline tests - -In order to run tests locally, you'll need `TA-lib`__, which you can install on Linux by running: - -__ https://mrjbq7.github.io/ta-lib/install.html - -.. code-block:: bash - - $ wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz - $ tar -xvzf ta-lib-0.4.0-src.tar.gz - $ cd ta-lib/ - $ ./configure --prefix=/usr - $ make - $ sudo make install - -And for ``TA-lib`` on OS X you can just run: - -.. code-block:: bash - - $ brew install ta-lib - -Then run ``pip install`` TA-lib: - -.. code-block:: bash - - $ pip install -r ./etc/requirements_talib.txt - -You should now be free to run tests: - -.. code-block:: bash - - $ nosetests - - -Continuous Integration ----------------------- - -We use `Travis CI`__ for Linux-64 bit builds and `AppVeyor`__ for Windows-64 bit builds. - -.. note:: - - We do not currently have CI for OSX-64 bit builds. 32-bit builds may work but are not included in our integration tests. - -__ https://travis-ci.org/quantopian/zipline -__ https://ci.appveyor.com/project/quantopian/zipline - - -Packaging ---------- -To learn about how we build Zipline conda packages, you can read `this`__ section in our release process notes. - -__ release-process.html#uploading-conda-packages - Contributing to the Docs ------------------------ -If you'd like to contribute to the documentation on zipline.io, you can navigate to ``docs/source/`` where each `reStructuredText`__ (``.rst``) file is a separate section there. To add a section, create a new file called ``some-descriptive-name.rst`` and add ``some-descriptive-name`` to ``appendix.rst``. To edit a section, simply open up one of the existing files, make your changes, and save them. - -__ https://en.wikipedia.org/wiki/ReStructuredText - -We use `Sphinx`__ to generate documentation for Zipline, which you will need to install by running: - -__ http://www.sphinx-doc.org/en/stable/ +If you'd like to contribute to the documentation on enigmampc.github.io, you can navigate to ``docs/source/`` where each `reStructuredText `_ file is a separate section there. To add a section, create a new file called ``some-descriptive-name.rst`` and add ``some-descriptive-name`` to ``index.rst``. To edit a section, simply open up one of the existing files, make your changes, and save them. +We use `Sphinx `_ to generate documentation for Catalyst, which you will need to install by running: .. code-block:: bash @@ -149,7 +78,7 @@ To build and view the docs locally, run: .. code-block:: bash - # assuming you're in the Zipline root directory + # assuming you're in the Catalyst root directory $ cd docs $ make html $ {BROWSER} build/html/index.html @@ -162,7 +91,7 @@ Standard prefixes to start a commit message: .. code-block:: text - BLD: change related to building Zipline + BLD: change related to building Catalyst BUG: bug fix DEP: deprecate something, or remove a deprecated object DEV: development tool or utility @@ -172,15 +101,13 @@ Standard prefixes to start a commit message: REV: revert an earlier commit STY: style fix (whitespace, PEP8, flake8, etc) TST: addition or modification of tests - REL: related to releasing Zipline + REL: related to releasing Catalyst PERF: performance enhancements Some commit style guidelines: -Commit lines should be no longer than `72 characters`__. 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. - -__ https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project +Commit lines should be no longer than `72 characters `_. 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. **Example:** @@ -203,8 +130,6 @@ __ https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project Formatting Docstrings --------------------- -When adding or editing docstrings for classes, functions, etc, we use `numpy`__ as the canonical reference. - -__ https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt +When adding or editing docstrings for classes, functions, etc, we use `numpy `_ as the canonical reference. diff --git a/docs/source/index.rst b/docs/source/index.rst index c3e0a19a..f0efbd6d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -11,6 +11,7 @@ Table of Contents beginner-tutorial naming-convention videos + development-guidelines .. bundles .. development-guidelines .. appendix