Skip to content

Commit d321905

Browse files
imjonsnooowimjonsnooow
committed
Set up basic doc structure, and migrate information from STIX's GitHub wiki.
1 parent 8234739 commit d321905

File tree

10 files changed

+369
-8
lines changed

10 files changed

+369
-8
lines changed

‎docs/_static/stix_doc.css‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
@import url("default.css");
2+
3+
/*
4+
Create styling for displaying elements side by side
5+
with equal horizontal space.
6+
*/
7+
.side-by-side {
8+
display: table;
9+
table-layout: fixed;
10+
11+
width: 100%;
12+
}
13+
14+
.side-by-side > * {
15+
display: table-cell;
16+
width: 50%;
17+
padding-right: 5px;
18+
}

‎docs/api/index.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
API Documentation
2+
=================
3+
4+
.. note::
5+
6+
The python-stix APIs are currently under development. As such, API coverage of STIX data constructs is incomplete; please bear with us as we work toward complete coverage. This documentation also serves to outline current API coverage.

‎docs/api_vs_bindings/api_snippet.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
.. code-block:: python
2+
3+
from datetime import datetime
4+
from stix.core import STIXPackage, STIXHeader
5+
from stix.common import InformationSource
6+
from cybox.common import Time
7+
8+
# Create the STIX Package and STIX Header objects
9+
stix_package = STIXPackage()
10+
stix_header = STIXHeader()
11+
12+
# Set the description
13+
stix_header.description = 'APIs vs. Bindings Wiki Example'
14+
15+
# Set the produced time to now
16+
stix_header.information_source = InformationSource()
17+
stix_header.information_source.time = Time()
18+
stix_header.information_source.time.produced_time = datetime.now()
19+
20+
# Build document
21+
stix_package.stix_header = stix_header
22+
23+
# Print the document to stdout
24+
print(stix_package.to_xml())

‎docs/api_vs_bindings/binding_snippet.rst‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
.. code-block:: python
2+
3+
import sys
4+
from datetime import datetime
5+
6+
import stix.bindings.stix_core as stix_core_binding
7+
import stix.bindings.stix_common as stix_common_binding
8+
import cybox.bindings.cybox_common as cybox_common_binding
9+
10+
# Create the STIX Package and STIX Header objects
11+
stix_package = stix_core_binding.STIXType()
12+
stix_header = stix_core_binding.STIXHeaderType()
13+
14+
# Set the description
15+
stix_header_description = stix_common_binding.StructuredTextType()
16+
stix_header_description.set_valueOf_('APIs vs. Bindings Wiki Example')
17+
18+
# Set the produced time to now
19+
stix_header_time = cybox_common_binding.TimeType()
20+
stix_header_time.set_Produced_Time(datetime.now())
21+
22+
# Bind the time to the STIX Header's Information Source element
23+
stix_header_info_source = stix_common_binding.InformationSourceType()
24+
stix_header_info_source.set_Time(stix_header_time)
25+
26+
# Build the document
27+
stix_header.set_Description(stix_header_description)
28+
stix_header.set_Information_Source(stix_header_info_source)
29+
stix_package.set_STIX_Header(stix_header)
30+
31+
# Print the document to stdout
32+
stix_package.export(sys.stdout, 0, stix_core_binding.DEFAULT_XML_NS_MAP)

‎docs/api_vs_bindings/index.rst‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
APIs or bindings?
2+
=================
3+
4+
This page describes both the **APIs** and the **bindings** provided by the *python-stix* library.
5+
6+
Overview
7+
--------
8+
9+
The python-stix library provides APIs and utilities that aid in the creation, consumption, and processing of Structured Threat Information eXpression (STIX) content. The APIs that drive much of the functionality of python-stix sit on top of a binding layer that acts as a direct connection between Python and the STIX XML. Because both the APIs and the bindings allow for the creation and development of STIX content, developers that are new to python-stix may not understand the differences between the two. This document aims to identify the purpose and uses of the APIs and bindings.
10+
11+
Bindings
12+
--------
13+
14+
The python-stix library leverages machine generated XML-to-Python bindings for the creation and processing of STIX content. These bindings are created using the `generateDS`_ utility and can be found under `stix.bindings`_ within the package hierarchy.
15+
16+
The STIX bindings allow for a direct, complete mapping between Python classes and STIX XML Schema data structures. That being said, it is possible (though not advised) to use only the STIX bindings to create STIX documents. However, because the code is generated from XML Schema without contextual knowledge of relationships or broader organizational/developmental schemes, it is often a cumbersome and laborious task to create even the simplest of STIX documents.
17+
18+
Developers within the python-stix team felt that the binding code did not lend itself to rapid development or natural navigation of data, and so it was decided that a higher-level API should be created.
19+
20+
.. _generateDS: http://www.rexx.com/~dkuhlman/generateDS.html
21+
.. _stix.bindings: https://github.com/STIXProject/python-stix/tree/master/stix/bindings
22+
23+
APIs
24+
----
25+
26+
The python-stix APIs are classes and utilities that leverage the STIX bindings for the creation and processing of STIX content. The APIs are designed to behave more naturally when working with STIX content, allowing developers to conceptualize and interact with STIX documents as pure Python objects and not XML Schema objects.
27+
28+
The APIs provide validation of inputs, multiple input and output formats, more Pythonic access of data structure internals and interaction with classes, and better interpretation of a developers intent through datatype coercion and implicit instantiation.
29+
30+
.. note::
31+
32+
The python-stix APIs are under constant development. Our goal is to provide full API coverage of the STIX data structures, but not all structures are exposed via the APIs yet. Please refer to the :doc:`../api/index` for API coverage details.
33+
34+
Brevity Wins
35+
------------
36+
37+
The two code examples show the difference in creating and printing a simple STIX document consisting of only a STIX Package and a STIX Header with a description and produced time using the python-stix and python-cybox bindings. Both examples will produce the same STIX XML!
38+
39+
.. container:: side-by-side
40+
41+
.. container::
42+
43+
**API Example**
44+
45+
.. include:: api_snippet.rst
46+
47+
.. container::
48+
49+
**Binding Example**
50+
51+
.. include:: binding_snippet.rst
52+
53+
Feedback
54+
--------
55+
56+
If there is a problem with the APIs or bindings, or if there is functionality missing from the APIs that forces the use of the bindings, let us know in the `python-stix issue tracker`_
57+
58+
.. _python-stix issue tracker: https://github.com/STIXProject/python-stix/issues

‎docs/binding/index.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Bindings Documentation
2+
======================
3+
4+
.. note::
5+
6+
The python-stix bindings are auto-generated - see :doc:`../api_vs_bindings/index` for more details. The bindings documentation may be incomplete and/or inconsistent. Please bear with us as we determine the best solution for this documentation.

‎docs/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
pygments_style = 'sphinx'
3434

3535
html_theme = 'default'
36-
html_style = '/default.css'
36+
html_style = 'stix_doc.css'
3737
html_static_path = ['_static']
3838
htmlhelp_basename = 'python-stixdoc'
3939

‎docs/getting_started.rst‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
Getting Started
2+
===============
3+
4+
This page gives an introduction to **python-stix** and how to use it.
5+
6+
.. note::
7+
8+
This page is being actively worked on; feedback is always welcome.
9+
10+
Prerequisites
11+
-------------
12+
13+
The python-stix library provides an API for creating or processing STIX content. As such, it is a developer tool that can be leveraged by those who know Python 2.6/2.7 and are familiar with object-oriented programming practices, Python package layouts, and are comfortable with the installation of Python libraries. To contribute code to the python-stix repository, users must be familiar with `git`_ and `GitHub pull request`_ methodologies. Understanding XML, XML Schema, and the STIX language is also incredibly helpful when using python-stix in an application.
14+
15+
.. _git: http://git-scm.com/documentation
16+
.. _GitHub pull request: https://help.github.com/articles/using-pull-requests
17+
18+
Your First STIX Application
19+
---------------------------
20+
21+
Once you have installed python-stix, you can begin writing Python applications that consume or create STIX content!
22+
23+
.. note::
24+
25+
The *python-stix* library provides **bindings** and **APIs**, both of which can be used to parse and write STIX XML files. For in-depth description of the *APIs, bindings, and the differences between the two*, please refer to :doc:`api_vs_bindings/index`
26+
27+
Creating a STIX Package
28+
***********************
29+
30+
.. code-block:: python
31+
32+
from stix.core import STIXPackage, STIXHeader # Import the STIX Package and STIX Header APIs
33+
34+
stix_package = STIXPackage() # Create an instance of STIXPackage
35+
stix_header = STIXHeader() # Create an instance of STIXHeader
36+
stix_header.description = "Getting Started!" # Set the description
37+
stix_package.stix_header = stix_header # Link the STIX Head to our STIX Package
38+
39+
print(stix_package.to_xml()) # print the XML for this STIX Package
40+
41+
Parsing STIX XML
42+
****************
43+
44+
.. code-block:: python
45+
46+
from stix.core import STIXPackage # Import the STIX Package API
47+
48+
fn = 'stix_content.xml' # The STIX content filename
49+
stix_package = STIXPackage.from_xml(fn) # Parse using the from_xml() method
50+
51+
Examples
52+
--------
53+
54+
The python-stix GitHub repository contains several example scripts that help illustrate the capabilities of the APIs. These examples can be found `here`_. These scripts are simple command line utilities that can be executed by passing the name of the script to a Python interpreter.
55+
56+
.. _here: https://github.com/STIXProject/python-stix/tree/master/examples
57+
58+
.. code-block:: python
59+
60+
Example:
61+
$ python ex_01.py
62+
63+
.. note::
64+
65+
You must install python-stix before running these example scripts.

‎docs/index.rst‎

Lines changed: 35 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,45 @@
1-
.. python-stix documentation master file, created by
2-
sphinx-quickstart on Thu May 1 10:23:56 2014.
3-
You can adapt this file completely to your liking, but it should at least
4-
contain the root `toctree` directive.
1+
python-stix |release| Documentation
2+
===================================
53

6-
Welcome to python-stix's documentation!
7-
=======================================
4+
The **python-stix** library provides an API for developing and consuming *Structured Threat Information eXpression* (**STIX**) content. Developers can leverage the API to develop applications that create, consume, translate, or otherwise process STIX content. This page should help new developers get started with using this library. For more information about STIX, please refer to the `STIX website`_.
85

9-
Contents:
6+
.. note::
7+
8+
These docs provide standard reference for this Python library. For documentation on *idiomatic* usage and *common patterns*, as well as various STIX-related information and utilities, please visit the `STIXProject at GitHub`_.
9+
10+
.. _STIXProject at GitHub: http://stixproject.github.io/
11+
12+
.. _STIX website: http://stix.mitre.org
13+
14+
.. toctree::
15+
:maxdepth: 2
16+
17+
installation
18+
getting_started
19+
api_vs_bindings/index
20+
21+
API Reference
22+
=============
1023

1124
.. toctree::
1225
:maxdepth: 2
1326

27+
api/index
28+
29+
Bindings Reference
30+
==================
31+
32+
.. toctree::
33+
:maxdepth: 2
34+
35+
binding/index
36+
37+
Contributing
38+
------------
39+
If a bug is found, a feature is missing, or something just isn't behaving the way you'd expect it to, please submit an issue to our `tracker`_. If you'd like to contribute code to our repository, you can do so by issuing a `pull request`_ and we will work with you to try and integrate that code into our repository.
1440

41+
.. _tracker: https://github.com/STIXProject/python-stix/issues
42+
.. _pull request: https://help.github.com/articles/using-pull-requests
1543

1644
Indices and tables
1745
==================

0 commit comments

Comments
 (0)