From d7efd1f752bd1b285966a4e7cdefc6e03700e134 Mon Sep 17 00:00:00 2001 From: Chris Lenk Date: Thu, 21 Sep 2017 17:27:13 -0400 Subject: [PATCH] Set up Sphinx autodoc This will automatically generate API documentation from docstrings. --- docs/_templates/autosummary/module.rst | 5 +++++ docs/api/stix2.base.rst | 5 +++++ docs/api/stix2.common.rst | 5 +++++ docs/api/stix2.core.rst | 5 +++++ docs/api/stix2.environment.rst | 5 +++++ docs/api/stix2.exceptions.rst | 5 +++++ docs/api/stix2.observables.rst | 5 +++++ docs/api/stix2.patterns.rst | 5 +++++ docs/api/stix2.properties.rst | 5 +++++ docs/api/stix2.sdo.rst | 5 +++++ docs/api/stix2.sro.rst | 5 +++++ docs/api/stix2.utils.rst | 5 +++++ docs/api_ref.rst | 7 +++++++ docs/conf.py | 19 ++++++++++++++++++- docs/guide.rst | 7 +++++++ docs/{ => guide}/creating.ipynb | 0 docs/{ => guide}/custom.ipynb | 0 docs/{ => guide}/markings.ipynb | 0 docs/{ => guide}/parsing.ipynb | 0 docs/{ => guide}/serializing.ipynb | 0 docs/{ => guide}/versioning.ipynb | 0 docs/index.rst | 10 +++------- stix2/__init__.py | 18 +++++++++++++++++- stix2/base.py | 2 +- 24 files changed, 113 insertions(+), 10 deletions(-) create mode 100644 docs/_templates/autosummary/module.rst create mode 100644 docs/api/stix2.base.rst create mode 100644 docs/api/stix2.common.rst create mode 100644 docs/api/stix2.core.rst create mode 100644 docs/api/stix2.environment.rst create mode 100644 docs/api/stix2.exceptions.rst create mode 100644 docs/api/stix2.observables.rst create mode 100644 docs/api/stix2.patterns.rst create mode 100644 docs/api/stix2.properties.rst create mode 100644 docs/api/stix2.sdo.rst create mode 100644 docs/api/stix2.sro.rst create mode 100644 docs/api/stix2.utils.rst create mode 100644 docs/api_ref.rst create mode 100644 docs/guide.rst rename docs/{ => guide}/creating.ipynb (100%) rename docs/{ => guide}/custom.ipynb (100%) rename docs/{ => guide}/markings.ipynb (100%) rename docs/{ => guide}/parsing.ipynb (100%) rename docs/{ => guide}/serializing.ipynb (100%) rename docs/{ => guide}/versioning.ipynb (100%) diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst new file mode 100644 index 0000000..37c15c8 --- /dev/null +++ b/docs/_templates/autosummary/module.rst @@ -0,0 +1,5 @@ +{{ name }} +{{ underline }} + +.. automodule:: {{ fullname }} + :members: diff --git a/docs/api/stix2.base.rst b/docs/api/stix2.base.rst new file mode 100644 index 0000000..459f2e5 --- /dev/null +++ b/docs/api/stix2.base.rst @@ -0,0 +1,5 @@ +base +========== + +.. automodule:: stix2.base + :members: \ No newline at end of file diff --git a/docs/api/stix2.common.rst b/docs/api/stix2.common.rst new file mode 100644 index 0000000..9e90b03 --- /dev/null +++ b/docs/api/stix2.common.rst @@ -0,0 +1,5 @@ +common +============ + +.. automodule:: stix2.common + :members: \ No newline at end of file diff --git a/docs/api/stix2.core.rst b/docs/api/stix2.core.rst new file mode 100644 index 0000000..f0e98d4 --- /dev/null +++ b/docs/api/stix2.core.rst @@ -0,0 +1,5 @@ +core +========== + +.. automodule:: stix2.core + :members: \ No newline at end of file diff --git a/docs/api/stix2.environment.rst b/docs/api/stix2.environment.rst new file mode 100644 index 0000000..fb5c7b7 --- /dev/null +++ b/docs/api/stix2.environment.rst @@ -0,0 +1,5 @@ +environment +================= + +.. automodule:: stix2.environment + :members: \ No newline at end of file diff --git a/docs/api/stix2.exceptions.rst b/docs/api/stix2.exceptions.rst new file mode 100644 index 0000000..a8d498e --- /dev/null +++ b/docs/api/stix2.exceptions.rst @@ -0,0 +1,5 @@ +exceptions +================ + +.. automodule:: stix2.exceptions + :members: \ No newline at end of file diff --git a/docs/api/stix2.observables.rst b/docs/api/stix2.observables.rst new file mode 100644 index 0000000..2d19996 --- /dev/null +++ b/docs/api/stix2.observables.rst @@ -0,0 +1,5 @@ +observables +================= + +.. automodule:: stix2.observables + :members: \ No newline at end of file diff --git a/docs/api/stix2.patterns.rst b/docs/api/stix2.patterns.rst new file mode 100644 index 0000000..ec7b42c --- /dev/null +++ b/docs/api/stix2.patterns.rst @@ -0,0 +1,5 @@ +patterns +============== + +.. automodule:: stix2.patterns + :members: \ No newline at end of file diff --git a/docs/api/stix2.properties.rst b/docs/api/stix2.properties.rst new file mode 100644 index 0000000..c3db9ff --- /dev/null +++ b/docs/api/stix2.properties.rst @@ -0,0 +1,5 @@ +properties +================ + +.. automodule:: stix2.properties + :members: \ No newline at end of file diff --git a/docs/api/stix2.sdo.rst b/docs/api/stix2.sdo.rst new file mode 100644 index 0000000..9448ff4 --- /dev/null +++ b/docs/api/stix2.sdo.rst @@ -0,0 +1,5 @@ +sdo +========= + +.. automodule:: stix2.sdo + :members: \ No newline at end of file diff --git a/docs/api/stix2.sro.rst b/docs/api/stix2.sro.rst new file mode 100644 index 0000000..a63af76 --- /dev/null +++ b/docs/api/stix2.sro.rst @@ -0,0 +1,5 @@ +sro +========= + +.. automodule:: stix2.sro + :members: \ No newline at end of file diff --git a/docs/api/stix2.utils.rst b/docs/api/stix2.utils.rst new file mode 100644 index 0000000..4091fb5 --- /dev/null +++ b/docs/api/stix2.utils.rst @@ -0,0 +1,5 @@ +utils +=========== + +.. automodule:: stix2.utils + :members: \ No newline at end of file diff --git a/docs/api_ref.rst b/docs/api_ref.rst new file mode 100644 index 0000000..11bf278 --- /dev/null +++ b/docs/api_ref.rst @@ -0,0 +1,7 @@ +API Reference +============= + +This section of documentation contains information on all of the classes and +functions in the ``stix2`` API, as given by the package's docstrings. + +.. automodule:: stix2 diff --git a/docs/conf.py b/docs/conf.py index 7f00421..9a3de50 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,7 +1,24 @@ +import os +import sys + +sys.path.insert(0, os.path.abspath('..')) + extensions = [ 'sphinx-prompt', 'nbsphinx', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.napoleon', ] +autodoc_default_flags = [ + 'show-inheritance', + 'undoc-members', +] +autodoc_member_order = 'groupwise' +autosummary_generate = True +napoleon_numpy_docstring = False # Force consistency, leave only Google +napoleon_use_rtype = False + templates_path = ['_templates'] source_suffix = '.rst' master_doc = 'index' @@ -14,7 +31,7 @@ version = '0.2.0' release = '0.2.0' language = None -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build', '_templates', 'Thumbs.db', '.DS_Store', '.ipynb_checkpoints'] pygments_style = 'sphinx' todo_include_todos = False diff --git a/docs/guide.rst b/docs/guide.rst new file mode 100644 index 0000000..80d2fb3 --- /dev/null +++ b/docs/guide.rst @@ -0,0 +1,7 @@ +User's Guide +============ + +.. toctree:: + :glob: + + guide/* diff --git a/docs/creating.ipynb b/docs/guide/creating.ipynb similarity index 100% rename from docs/creating.ipynb rename to docs/guide/creating.ipynb diff --git a/docs/custom.ipynb b/docs/guide/custom.ipynb similarity index 100% rename from docs/custom.ipynb rename to docs/guide/custom.ipynb diff --git a/docs/markings.ipynb b/docs/guide/markings.ipynb similarity index 100% rename from docs/markings.ipynb rename to docs/guide/markings.ipynb diff --git a/docs/parsing.ipynb b/docs/guide/parsing.ipynb similarity index 100% rename from docs/parsing.ipynb rename to docs/guide/parsing.ipynb diff --git a/docs/serializing.ipynb b/docs/guide/serializing.ipynb similarity index 100% rename from docs/serializing.ipynb rename to docs/guide/serializing.ipynb diff --git a/docs/versioning.ipynb b/docs/guide/versioning.ipynb similarity index 100% rename from docs/versioning.ipynb rename to docs/guide/versioning.ipynb diff --git a/docs/index.rst b/docs/index.rst index 4b71958..62d07ff 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,16 +7,12 @@ Welcome to stix2's documentation! ================================= .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :caption: Contents: overview - creating - serializing - parsing - versioning - markings - custom + guide + api_ref datastore_api roadmap contributing diff --git a/stix2/__init__.py b/stix2/__init__.py index f472fc3..cfc6386 100644 --- a/stix2/__init__.py +++ b/stix2/__init__.py @@ -1,4 +1,20 @@ -"""Python APIs for STIX 2.""" +"""Python APIs for STIX 2. + +.. autosummary:: + :toctree: api + + base + common + core + environment + exceptions + observables + patterns + properties + sdo + sro + utils +""" # flake8: noqa diff --git a/stix2/base.py b/stix2/base.py index 5608102..5307393 100644 --- a/stix2/base.py +++ b/stix2/base.py @@ -1,4 +1,4 @@ -"""Base class for type definitions in the stix2 library.""" +"""Base classes for type definitions in the stix2 library.""" import collections import copy