wassname/catalyst
1
0
Fork 0
mirror of https://github.com/wassname/catalyst.git synced 2026-08-09 11:50:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

DOC: documenting the documentation

Browse Source
This commit is contained in:
Victor Grau Serrat
2017-10-30 13:54:27 -06:00
parent eaefe4a908
commit 13f023d364
2 changed files with 31 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/development-guidelines.rst
+30 -105
View File
@@ -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 <https://github.com/enigmampc/catalyst/issues>`_ on `GitHub <https://github.com/enigmampc/catalyst>`_ and also have a `discord group <https://discord.gg/SJK32GY>`_ 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 <install.html>`_ 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 <http://nvie.com/posts/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 <https://en.wikipedia.org/wiki/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 <http://www.sphinx-doc.org/en/stable/>`_ 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 <https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project>`_. 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 <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ as the canonical reference.
docs/source/index.rst
+1
View File
@@ -11,6 +11,7 @@ Table of Contents
beginner-tutorial
naming-convention
videos
development-guidelines
.. bundles
.. development-guidelines
.. appendix