Initial documentation.

docs/contributing.rst

@@ -0,0 +1,93 @@
+Contributing
+============
+
+We're thrilled that you're interested in contributing to python-stix2! Here are
+some things you should know:
+
+- `contribution-guide.org <http://www.contribution-guide.org/>`_ has great ideas
+  for contributing to any open-source project (not just python-stix2).
+- All contributors must sign a Contributor License Agreement. See
+  `CONTRIBUTING.md <https://github.com/oasis-open/cti-python-stix2/blob/master/CONTRIBUTING.md>`_
+  in the project repository for specifics.
+- If you are planning to implement a major feature (vs. fixing a bug), please
+  discuss with a project maintainer first to ensure you aren't duplicating the
+  work of someone else, and that the feature is likely to be accepted.
+
+Now, let's get started!
+
+Setting up a development environment
+------------------------------------
+
+We recommend using a `virtualenv <https://virtualenv.pypa.io/en/stable/>`_.
+
+1. Clone the repository. If you're planning to make pull request, you should fork
+the repository on GitHub and clone your fork instead of the main repo::
+
+    $ git clone https://github.com/yourusername/cti-python-stix2.git
+
+2. Install develoment-related dependencies::
+
+    $ cd cti-python-stix2
+    $ pip install -r requirements.txt
+
+At this point you should be able to make changes to the code.
+
+Code style
+----------
+
+All code should follow `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_. We
+allow for line lengths up to 160 characters, but any lines over 80 characters
+should be the exception rather than the rule. PEP 8 conformance will be tested
+automatically by Tox and Travis-CI (see below).
+
+Testing
+-------
+
+.. note::
+
+    All of the tools mentioned in this section are installed when you run ``pip
+    install -r requirements.txt``.
+
+python-stix2 uses `pytest <http://pytest.org>` for testing.  We encourage the
+use of test-driven development (TDD), where you write (failing) tests that
+demonstrate a bug or proposed new feature before writing code that fixes the bug
+or implements the features. Any code contributions to python-stix2 should come
+with new or updated tests.
+
+To run the tests in your current Python environment, use the ``pytest`` command
+from the root project directory::
+
+     $ pytest
+
+This should show all of the tests that ran, along with their status.
+
+You can run a specific test file by passing it on the command line::
+
+    $ pytest stix2/test/test_<xxx>.py
+
+To ensure that the test you wrote is running, you can deliberately add an
+``assert False`` statement at the beginning of the test. This is another benefit
+of TDD, since you should be able to see the test failing (and ensure it's being
+run) before making it pass.
+
+`tox <https://tox.readthedocs.io/en/latest/>`_ allows you to test a package
+across multiple versions of Python. Setting up multiple Python environments is
+beyond the scope of this guide, but feel free to ask for help setting them up.
+Tox should be run from the root directory of the project:::
+
+   $ tox
+
+We aim for high test coverage, using the `coverage.py
+<http://coverage.readthedocs.io/en/latest/>`_ library. Though it's not an
+absolute requirement to maintain 100% coverage, all code contributions must
+be accompanied by tests. To run coverage and look for untested lines of code,
+run::
+
+    $ pytest --cov=stix2
+    $ coverage html
+
+then look at the resulting report in ``htmlcov/index.html``.
+
+All commits pushed to the ``master`` branch or submitted as a pull request is
+tested with `Travis-CI <https://travis-ci.org/oasis-open/cti-python-stix2>`
+automatically.

docs/datastore_api.rst

@@ -0,0 +1,39 @@
+.. _datastore_api:
+
+DataStore API
+=============
+
+.. warning::
+
+    The DataStore API is still in the planning stages and may be subject to
+    major changes. We encourage anyone with feedback to contact the maintainers
+    to help ensure the API meets a large variety of use cases.
+
+One prominent feature of python-stix2 will be an interface for connecting
+different backend data stores containing STIX content. This will allow a uniform
+interface for querying and saving STIX content, and allow higher level code to
+be written without regard to the underlying data storage format. python-stix2
+will define the API and contain some default implementations of this API, but
+developers are encouraged to write their own implementations.
+
+Potential functions of the API include:
+
+* get a STIX Object by ID (returns the most recent version).
+* get all versions of a STIX object by ID.
+* get all relationships involving a given object, and all related objects.
+* save an object.
+* query for objects that match certain criteria (query syntax TBD).
+
+For all queries, the API will include a "filter" interface that can be used to
+either explicitly include or exclude results with certain criteria. For example,
+
+* only trust content from a set of object creators.
+* exclude content from certain (untrusted) object creators.
+* only include content with a confidence above a certain threshold (once
+  confidence is added to STIX).
+* only return content that can be shared with external parties (in other words,
+  that has TLP:GREEN markings).
+
+Additionally, the python-stix2 library will contain a "composite" data store,
+which implements the DataStore API while delegating functionality to one or more
+"child" data store.

docs/index.rst

@@ -10,6 +10,10 @@ Welcome to stix2's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   overview
+   roadmap
+   datastore_api
+   contributing
 
 
 Indices and tables

docs/overview.rst

@@ -0,0 +1,24 @@
+Overview
+========
+
+High level goals/principles of the python-stix2 library:
+
+1. It should be as easy as possible (but no easier!) to perform common tasks of
+   producing, consuming, and processing STIX 2 content.
+2. It should be hard, if not impossible, to emit invalid STIX 2.
+3. The library should default to doing "the right thing", complying with both
+   the STIX 2.0 spec, as well as associated best practices. The library should
+   make it hard to do "the wrong thing".
+
+To accomplish these goals, and to incorporate lessons learned while developing
+python-stix (for STIX 1.x), several decisions influenced the design of
+python-stix2:
+
+1. All data structures are immutable by default. In contrast to python-stix,
+   where users would create an object and then assign attributes to it, in
+   python-stix2 all properties must be provided when creating the object.
+2. Where necessary, library objects should act like ``dict``'s. When treated as
+   a ``str``, the JSON reprentation of the object should be used.
+3. Core Python data types (including numeric types, ``datetime``) should be used
+   when appropriate, and serialized to the correct format in JSON as specified
+   in the STIX 2.0 spec.

docs/roadmap.rst

@@ -0,0 +1,17 @@
+Development Roadmap
+===================
+
+.. warning::
+
+    Prior to version 1.0, all APIs are considered unstable and subject to
+    change.
+
+This is a list of (planned) features before version 1.0 is released.
+
+* Serialization of all STIX and Cyber Observable objects to JSON.
+* De-serialization (parsing) of all STIX and Cyber Observable objects.
+* APIs for versioning (revising and revoking) STIX objects.
+* APIs for marking STIX objects and interpreting markings of STIX objects.
+* :ref:`datastore_api`, providing a common interface for querying sources
+  of STIX content (such as objects in memory, on a filesystem, in a database, or
+  via a TAXII feed).