Sphinx documentation added in preparation for ReadTheDocs.io link-up.…

… 'index' page first draft complete, but still need to look at 'Getting Started', 'QSTrader Examples' and 'API Reference'.

docs/Makefile

@@ -0,0 +1,225 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  epub3      to make an epub3"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+	@echo "  dummy      to check syntax errors of document sources"
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: dirhtml
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: pickle
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+.PHONY: json
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+.PHONY: htmlhelp
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+.PHONY: qthelp
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/QSTrader.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/QSTrader.qhc"
+
+.PHONY: applehelp
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+.PHONY: devhelp
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/QSTrader"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/QSTrader"
+	@echo "# devhelp"
+
+.PHONY: epub
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: epub3
+epub3:
+	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
+	@echo
+	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
+
+.PHONY: latex
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+.PHONY: latexpdf
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: text
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: man
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+.PHONY: texinfo
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+.PHONY: info
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+.PHONY: changes
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+.PHONY: linkcheck
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: xml
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+.PHONY: pseudoxml
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+.PHONY: dummy
+dummy:
+	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
+	@echo
+	@echo "Build finished. Dummy builder generates no files."

docs/_build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: ba550ac379e752691f50efff07d6b087
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_build/html/_sources/getting-started.txt

@@ -0,0 +1,3 @@
+Getting Started with QSTrader
+=============================
+

docs/_build/html/_sources/index.txt

@@ -0,0 +1,142 @@
+.. QSTrader documentation master file, created by
+   sphinx-quickstart on Wed Mar 15 09:57:57 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to QSTrader's documentation!
+====================================
+
+.. image:: https://travis-ci.org/mhallsmoore/qstrader.svg?branch=master
+   :target: https://travis-ci.org/mhallsmoore/qstrader
+
+.. image:: https://coveralls.io/repos/github/mhallsmoore/qstrader/badge.svg?branch=master
+   :target: https://coveralls.io/github/mhallsmoore/qstrader?branch=master
+
+.. image:: https://img.shields.io/badge/license-MIT%20License-blue.svg
+   :target: https://github.com/mhallsmoore/qstrader/blob/master/LICENSE
+
+.. image:: https://img.shields.io/badge/python-2.7%2C%203.4%2C%203.5-blue.svg
+   :target: https://coveralls.io/github/mhallsmoore/qstrader?branch=master
+
+QSTrader is an open source Python library for event-driven backtesting and live trading of the US equities markets with a focus on realistic simulation, modularity and extensibility. It is currently in an alpha state but is under heavy development.
+
+QSTrader is designed for "power users" who want a broad framework to tie their systematic trading together, but which provides extensive customisation in the areas of market data handling, portfolio/order management, risk, position sizing and execution.
+
+It has been designed both for a wide variety of use cases, from end-of-day retail traders through to small intraday quant funds trading at intraday frequencies.
+
+The software is provided under a permissive commercial-friendly "MIT" license (:ref:`see below <ref-license>`).
+
+Check out the :doc:`getting started guide </getting-started>`!
+
+.. image:: https://s3.amazonaws.com/quantstart/media/images/qstrader-moving-average-cross-tearsheet.png
+
+Features
+--------
+
+* **Event-Driven Architecture** - QSTrader is completely event-driven, allowing backtesting and live trading at a wide range of frequencies. The event-driven architecture allows "event generator" modules to be added easily, such as sentiment analysis signal generators, market data generators and risk manager generators.
+
+* **Modular Design** - QSTrader ships with basic modules for backtesting and live trading. While these modules contain sensible, realistic defaults, they are designed to be fully extended and customised for those with more specific requirements.
+
+* **Data** - QSTrader supports multiple data source formats, predominantly CSV files of the major vendors such as Yahoo Finance and DTN IQFeed. It supports tick-resolution (top of order book bid/ask) as well as OHLCV "bar" resolution data on various time scales. It is straightforward to add other vendors into the system by subclassing the PriceHandler module.
+
+* **Backtesting** - QSTrader provides an efficient, out-of-the-box backtesting system for daily equities using Yahoo Finance data, with realistic position-handling and sensible defaults for transaction cost simulation. All behaviour is fully customisable allowing you to define your own transaction cost methodology.
+
+* **Performance Metrics** - QSTrader supports both portfolio-level and trade-level performance measurement, displayed through a comprehensive visual "tearsheet" for a portfolio. Backtesting statistics can be exported and viewed through other reporting tools, such as Excel.
+
+Getting Started
+---------------
+
+* The :doc:`QSTrader tutorial </getting-started>`
+* :doc:`QSTrader examples </examples>` and :doc:`API reference </api>`
+* The `original announcement post <https://www.quantstart.com/articles/Announcing-the-QuantStart-Advanced-Trading-Infrastructure-Article-Series>`_ on QuantStart.com
+
+
+Installation
+------------
+
+QSTrader is in an early alpha state at the moment. It should only be used for **exploratory backtesting research**. The installation procedure is a little more involved than a standard Python package as it has not yet been added to the Python package repository.
+
+**Ubuntu Linux is the recommended platform** on which to install QSTrader, but it will also work on Windows or Mac OSX under the `Anaconda distribution <https://www.continuum.io/downloads>`_.
+
+The following steps will create a virtual environment directory with Python 3 and then activate the environment. Please change :code:`~/venv/qstraderp3` to your preferred virtual environment directory in the following::
+
+    mkdir -p ~/venv/qstraderp3
+    cd ~/venv/qstraderp3
+    virtualenv --no-site-packages -p python3 .
+    source ~/venv/qstraderp3/bin/activate
+
+At this point it is necessary to use pip to install QSTrader as a library and then manually install the requirements. The following steps will take some time (5-10 minutes) as QSTrader relies on NumPy, SciPy, Pandas, Matplotlib as well as many other libraries and hence they will all need to compile::
+
+    pip install git+https://github.com/mhallsmoore/qstrader.git
+    pip install -r https://raw.githubusercontent.com/mhallsmoore/qstrader/master/requirements.txt
+
+Now that the library itself and requirements have been installed it is necessary to create the default directories for the data and output. This will allow the example code to be run::
+
+    mkdir -p ~/qstrader/examples ~/data ~/out
+
+Now that the code has been installed and example directories created the :doc:`getting started guide </getting-started>` should be consulted on how to run some trading strategy backtests.
+
+Development
+-----------
+
+* **Cross Platform** - QSTrader is written in the Python programming language for straightforward cross-platform support.
+
+* **Testing** - QSTrader contains a suite of unit tests for the majority of its calculation code and these tests are executed upon every change to the code. Additional tests are constantly added for both current and new features.
+
+* **Collaboration** - As QSTrader is open source many developers collaborate to improve the software. New features are added frequently. Any bugs are quickly determined and fixed.
+
+*The project is constantly being developed so unfortunately it is likely that the current API will experience backwards incompatibility until a mature beta version has been produced.*
+
+Contributors
+------------
+
+* `Michael Halls-Moore <https://github.com/mhallsmoore/>`_
+* `Ryan Kennedy <https://github.com/ryankennedyio>`_
+* `FemtoTrader <https://github.com/femtotrader>`_
+* `Nick Willemse <https://github.com/nwillemse>`_
+
+Sponsors
+--------
+
+.. image:: images/qs-logo.png
+   :target: https://www.quantstart.com/
+
+.. _ref-license:
+
+Contact/Support
+---------------
+
+To report an issue with QSTrader or to suggest a feature please use the `issue tracker <https://github.com/mhallsmoore/qstrader/issues/>`_.
+
+To interact with QSTrader developers email `mike@quantstart.com <mike@quantstart.com>`_ for a Slack invite.
+
+License Terms
+-------------
+
+Copyright (c) 2015-2017 Michael Halls-Moore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Trading Disclaimer
+------------------
+
+Trading equities on margin carries a high level of risk, and may not be suitable for all investors. Past performance is not indicative of future results. The high degree of leverage can work against you as well as for you. Before deciding to invest in equities you should carefully consider your investment objectives, level of experience, and risk appetite. The possibility exists that you could sustain a loss of some or all of your initial investment and therefore you should not invest money that you cannot afford to lose. You should be aware of all the risks associated with equities trading, and seek advice from an independent financial advisor if you have any doubts.
+
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+